Dify 对接火山方舟全流程避坑指南（插件下载失败问题处理）
Dify 对接火山方舟全流程指南（插件下载失败问题处理）
📌 本文适用场景：国内服务器部署 Dify，对接火山方舟，解决插件安装失败、模型配置异常等核心问题，全程使用阿里云 PyPI 镜像加速，新手可直接照做。
目录
一、背景与目标
二、核心问题与解决方案汇总（重点！）
2.1 问题1：插件安装失败（Network connectivity is disabled）
2.2 问题2：Embedding 模型找不到
2.3 问题3：系统模型尚未完全配置
三、火山方舟大模型操作全流程（分步实操）
3.1 步骤1：创建对话模型接入点
3.2 步骤2：创建 Embedding 模型接入点
3.3 步骤3：Dify 侧模型配置
五、总结与避坑要点
六、附录：关键配置片段（直接复制）
一、背景与目标
在国内网络环境下，部署 Dify 并对接火山方舟（豆包大模型）时，频繁出现插件安装失败、依赖下载超时、模型配置后无法选择等问题。
本文核心目标：完整记录从 Dify 插件安装到智能体可用的全流程，拆解所有踩坑点及对应解决方案，全程采用阿里云 PyPI 镜像加速依赖下载，确保国内环境一次性部署成功，新手也能快速上手。
二、核心问题与解决方案汇总（重点！）
以下是对接过程中最常见的4个问题，每个问题均附「现象+根因+可直接复制的解决方案」，无需额外调试。
2.1 问题1：Dify 安装火山方舟插件失败，报错 Network connectivity is disabled
现象
插件安装时提示
Failed to download volcengine-python-sdk日志显示
Network connectivity is disabled，或出现下载超时、进程被 killed（signal: killed）
根因
Dify 插件依赖
uv工具安装 Python 包，默认从国外 PyPI 源（pypi.org）下载，国内网络无法稳定访问（被墙、超时、丢包）。插件默认初始化超时时间为 120s，国内网络下载大依赖包（如 volcengine-python-sdk）时，时间不足导致超时失败。
解决方案（阿里云镜像版，直接复制配置）
修改 Dify 根目录下的docker-compose.yml文件，重点修改plugin_daemon和api两个服务的环境变量，配置阿里云 PyPI 镜像并延长超时时间。
# 重点修改 plugin_daemon 服务plugin_daemon:environment:# 延长初始化超时时间（从120s改为600s），避免国内网络过慢导致超时PYTHON_ENV_INIT_TIMEOUT:600# 配置阿里云 PyPI 镜像，加速依赖下载（核心！）PIP_MIRROR_URL:https://mirrors.aliyun.com/pypi/simple/# 补充修改 api 服务，确保 uv 也使用阿里云镜像api:environment:UV_NO_NETWORK:"0"# 明确允许网络访问，避免误判无网络UV_INDEX_URL:https://mirrors.aliyun.com/pypi/simple/# uv 镜像PIP_INDEX_URL:https://mirrors.aliyun.com/pypi/simple/# pip 镜像# 其他原有环境变量不变，保留即可修改完成后，执行以下命令重启 Dify 容器，使配置生效：
docker-composedown&&docker-composeup-d提示：重启后可通过以下命令验证配置是否生效，确保镜像地址和超时时间正确：
正常输出应为：PYTHON_ENV_INIT_TIMEOUT=600、PIP_MIRROR_URL=https://mirrors.aliyun.com/pypi/simple/
docker exec -it docker-plugin_daemon-1 env | grep -E "PYTHON_ENV_INIT_TIMEOUT|PIP_MIRROR_URL"
2.2 问题2：火山方舟模型配置后，系统推理模型能选到，但 Embedding 模型找不到
现象
Dify 「系统模型设置」中，「系统推理模型」下拉框能正常看到火山方舟-Doubao 模型。
「Embedding 模型」下拉框提示
No model found for ""，无法选择火山方舟相关模型。
根因
Dify 严格区分模型类型：「系统推理模型」对应LLM（对话模型），「Embedding 模型」对应Text Embedding（向量模型）；你仅在火山方舟部署了对话模型，未部署 Embedding 向量模型，因此无法找到。
解决方案（分步实操）
需分两步：先在火山方舟部署 Embedding 模型，再在 Dify 中添加该模型。
第一步：火山方舟侧部署 Embedding 模型
登录火山方舟控制台 → 左侧菜单栏「智能广场」→「模型广场」。
顶部筛选「文本嵌入」类型，选择适合的模型（新手推荐
bge-large-zh-v1.5或m3e-base，轻量且免费）。进入模型详情页，点击「部署」→「在线推理」，选择「自定义推理接入点」。
配置资源规格（测试用选最小规格即可），点击「确认创建」，等待 1~3 分钟部署完成。
部署完成后，进入「模型推理」→「在线推理」，找到刚创建的 Embedding 接入点，记录其
Endpoint ID（格式：ep-m-xxxxxxx）。
第二步：Dify 侧添加 Embedding 模型
进入 Dify 控制台 → 右上角「设置」→「模型供应商」→「火山方舟」→「添加模型」。
按以下表格填写配置（AK/SK 与对话模型一致，无需重新获取）：
| 字段 | 填写内容 |
|---|---|
| 模型名称 | 火山方舟-Embedding（自定义，便于识别） |
| 模型类型 | 下拉选择「Text Embedding」 |
| 凭据名称 | 可复用对话模型的凭据，或新建为「火山方舟-Embedding凭据」 |
| 鉴权方式 | 保持「Access Key / Secret Access Key」 |
| Access Key | 火山引擎 AK（与对话模型一致） |
| Secret Access Key | 火山引擎 SK（与对话模型一致） |
| 火山引擎地域 | 保持「cn-beijing」（与接入点地域一致） |
| API Endpoint Host | 保持「https://ark.cn-beijing.volces.com/api/v3」 |
| Endpoint ID | 刚部署的 Embedding 接入点 ID（如 ep-m-xxxxxxx） |
| 基础模型 | 选择「自定义」 |
| 模型上下文长度 | 按模型官方标注填写（如 bge-large-zh-v1.5 填 512） |
| 填写完成后点击「添加」，返回「系统模型设置」，即可在 Embedding 模型下拉框中看到该模型。 |
2.3 问题3：系统模型提示「尚未完全配置」
现象
Dify 模型供应商页面顶部提示「系统模型尚未完全配置」，新建应用时无法选择模型，无法正常使用。
根因
已添加火山方舟模型，但未将其设置为 Dify 的「系统默认模型」，系统无法识别可用模型。
解决方案
在 Dify 模型供应商页面，点击顶部提示中的「系统模型设置」。
「系统推理模型」：下拉选择已添加的「火山方舟-Doubao」。
（可选）「Embedding 模型」：下拉选择已添加的「火山方舟-Embedding」。
点击页面底部「保存」，提示消失，系统模型配置完成。
三、火山方舟大模型操作全流程（分步实操）
汇总火山方舟侧「对话模型+Embedding模型」的部署步骤，配合 Dify 配置，确保全程无遗漏。
3.1 步骤1：创建对话模型接入点（LLM）
登录火山方舟控制台 → 左侧「模型推理」→「在线推理」。
点击「创建接入点」，选择「预置推理接入点」（新手推荐，无需手动配置资源）或「自定义推理接入点」。
选择对话模型（如
Doubao-Seed-2.0-pro，根据需求选择轻量版/标准版）。配置资源规格（测试用选最小规格），点击「确认创建」，等待 1~2 分钟部署完成。
部署完成后，记录该接入点的
Endpoint ID（后续 Dify 配置需用到）。
3.2 步骤2：创建 Embedding 模型接入点
详细步骤见 2.2 问题的解决方案（第一步），核心是「筛选文本嵌入模型→部署在线推理→记录 Endpoint ID」，此处不再重复。
3.3 步骤3：Dify 侧模型配置（完整流程）
修改
docker-compose.yml，配置阿里云镜像+延长超时（见 2.1 解决方案），重启 Dify 容器。安装火山方舟插件：Dify → 模型供应商 → 火山方舟 → 点击「安装插件」，等待安装完成（无报错即成功）。
添加对话模型：按前文配置，模型类型选「LLM」，填入对话模型的 Endpoint ID、AK/SK。
添加 Embedding 模型：按前文配置，模型类型选「Text Embedding」，填入 Embedding 模型的 Endpoint ID、AK/SK。
系统模型设置：指定推理模型和 Embedding 模型，保存生效。
五、总结与避坑要点
以下是对接过程中最关键的避坑要点，新手必看！
核心坑点：国内环境插件安装失败，本质是国外 PyPI 源无法访问 → 用阿里云镜像+延长超时，一次性解决。
模型区分：LLM 负责对话生成，Embedding 负责知识库检索，需分别部署、分别配置，不可混淆。
AK/SK 复用：火山引擎的 AK/SK 是账号级通用密钥，对话模型、Embedding 模型可复用，无需重复创建。
最小可用配置：仅部署 LLM 即可实现纯对话智能体，Embedding 是知识库功能的前提，可按需选择是否部署。
Rerank 优化：非必需，新手可先跑通基础功能，后续再根据业务需求补充，提升回答精度。
六、附录：关键配置片段（直接复制）
为避免手动输入出错，此处提供docker-compose.yml核心修改片段，直接复制替换原有内容即可。
# docker-compose.yml 核心修改片段（仅展示需修改的部分）version:'3.8'services:api:image:langgenius/dify-api:latestrestart:alwaysenvironment:<<:*shared-api-worker-envMODE:apiUV_NO_NETWORK:"0"UV_INDEX_URL:https://mirrors.aliyun.com/pypi/simple/PIP_INDEX_URL:https://mirrors.aliyun.com/pypi/simple/# 其他原有环境变量不变，保留即可plugin_daemon:image:langgenius/dify-plugin-daemon:latestrestart:alwaysenvironment:<<:*shared-api-worker-envPYTHON_ENV_INIT_TIMEOUT:600PIP_MIRROR_URL:https://mirrors.aliyun.com/pypi/simple/# 其他原有环境变量不变，保留即可结尾
本文完整覆盖了国内环境下 Dify 对接火山方舟的全流程，从插件安装避坑、模型部署到智能体验证，每一步均有详细操作和代码片段，新手可直接照做。
如果在部署过程中遇到其他问题，欢迎在评论区留言交流，看到会第一时间回复～
（注：文档部分内容可能由 AI 生成）