必须接入Voyage AI text-embedding-v3模型并正确配置API参数才能在Dify中实现语义精准、响应快速的知识库检索，需严格遵循注册、密钥生成、Custom模型配置、参数模板设置及知识库绑定验证全流程。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Dify中启用语义精准、响应快速的知识库检索，必须接入高质量Embedding模型；Voyage AI提供的text-embedding-v3系列在多语言支持、长文本适配和向量区分度上表现突出，但其API结构与OpenAI不完全兼容，直接填入Dify默认配置会触发400错误或向量化失败。
确认Voyage AI账户并获取凭证
访问 voyageai.com 注册账号，完成邮箱验证后进入 Dashboard → API Keys 页面。
点击 “Create new API key”，输入名称（如 dify-prod-embed），勾选 text-embedding 权限，生成密钥。
【务必复制并安全保存该密钥——页面关闭后将无法再次查看】
记下 Base URL：https://api.voyageai.com/v1。注意末尾是 /v1，不是 /v1/ 或其他路径。
在Dify中新增Embedding模型实例
登录Dify控制台 → 左侧导航栏点击「设置」→「模型管理」→「Embedding模型」→「+ 新增模型」。
填写以下字段：
- 模型名称：例如 voyage-text-3-large（建议含版本号，便于后续区分）
- 模型供应商：选择 Custom（不要选 OpenAI 或其他预设项）
-
API Base URL：粘贴刚才记下的
https://api.voyageai.com/v1 - API Key：粘贴刚生成的密钥
-
模型名称（API参数）：填
voyage-text-3-large（大小写敏感，不可写成Voyage-Text-3-Large）
点击「保存」。此时模型状态显示为「未验证」——这是正常现象，验证需在下一步绑定知识库时触发。
配置Embedding参数模板
保存模型后，自动跳转至该模型的「参数模板」编辑页。
关键参数设置如下：
- dimension：留空（Voyage AI v3模型不接受客户端指定维度，强制填写会导致422错误）
-
input_type：填
document（用于知识库文档向量化）；若后续用于查询嵌入，需另建一个模板并设为query -
truncation：设为
true（Voyage默认不截断，但Dify对超长段落处理不稳定，开启后可避免500报错） -
max_tokens：填
32768（对应 voyage-text-3-large 的上下文上限，低于此值可能丢失语义）
保存参数模板。此时模型状态仍为「未验证」，尚未真正连通。
将Voyage模型绑定至知识库并触发验证
方法一：新建知识库时直接绑定
进入「知识库」→「+ 新建知识库」→ 填写名称和描述 → 在「Embedding 模型」下拉菜单中选择你刚创建的 voyage-text-3-large → 点击「创建」。
创建成功后，立即上传一个测试文档（如 1KB 的纯文本TXT），Dify会自动调用Voyage API执行首次向量化，并在后台日志中记录响应状态码。
方法二：为已有知识库更换Embedding模型
打开目标知识库 → 点击右上角「设置」图标 → 「Embedding 模型」→ 下拉选择 voyage-text-3-large → 点击「保存并重新索引」。
【注意：此操作会清空当前知识库全部向量索引，需重新上传文档或触发全量重同步】
等待索引完成（状态栏显示“已完成”），查看知识库「统计」页中的「向量总数」是否大于0。若为0或报错，说明API连通失败，需检查密钥权限或Base URL末尾斜杠。
