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-compose down && docker-compose up -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 模型

1. 登录火山方舟控制台 → 左侧菜单栏「智能广场」→「模型广场」。

2. 顶部筛选「文本嵌入」类型，选择适合的模型（新手推荐 bge-large-zh-v1.5 或 m3e-base，轻量且免费）。

3. 进入模型详情页，点击「部署」→「在线推理」，选择「自定义推理接入点」。

4. 配置资源规格（测试用选最小规格即可），点击「确认创建」，等待 1~3 分钟部署完成。

5. 部署完成后，进入「模型推理」→「在线推理」，找到刚创建的 Embedding 接入点，记录其 Endpoint ID（格式：ep-m-xxxxxxx）。

第二步：Dify 侧添加 Embedding 模型

1. 进入 Dify 控制台 → 右上角「设置」→「模型供应商」→「火山方舟」→「添加模型」。

2. 按以下表格填写配置（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 的「系统默认模型」，系统无法识别可用模型。

解决方案

1. 在 Dify 模型供应商页面，点击顶部提示中的「系统模型设置」。

2. 「系统推理模型」：下拉选择已添加的「火山方舟-Doubao」。

3. （可选）「Embedding 模型」：下拉选择已添加的「火山方舟-Embedding」。

4. 点击页面底部「保存」，提示消失，系统模型配置完成。

三、火山方舟大模型操作全流程（分步实操）

汇总火山方舟侧「对话模型+Embedding模型」的部署步骤，配合 Dify 配置，确保全程无遗漏。

3.1 步骤1：创建对话模型接入点（LLM）

1. 登录火山方舟控制台 → 左侧「模型推理」→「在线推理」。

2. 点击「创建接入点」，选择「预置推理接入点」（新手推荐，无需手动配置资源）或「自定义推理接入点」。

3. 选择对话模型（如 Doubao-Seed-2.0-pro，根据需求选择轻量版/标准版）。

4. 配置资源规格（测试用选最小规格），点击「确认创建」，等待 1~2 分钟部署完成。

5. 部署完成后，记录该接入点的 Endpoint ID（后续 Dify 配置需用到）。

3.2 步骤2：创建 Embedding 模型接入点

详细步骤见 2.2 问题的解决方案（第一步），核心是「筛选文本嵌入模型→部署在线推理→记录 Endpoint ID」，此处不再重复。

3.3 步骤3：Dify 侧模型配置（完整流程）

1. 修改 docker-compose.yml，配置阿里云镜像+延长超时（见 2.1 解决方案），重启 Dify 容器。

2. 安装火山方舟插件：Dify → 模型供应商 → 火山方舟 → 点击「安装插件」，等待安装完成（无报错即成功）。

3. 添加对话模型：按前文配置，模型类型选「LLM」，填入对话模型的 Endpoint ID、AK/SK。

4. 添加 Embedding 模型：按前文配置，模型类型选「Text Embedding」，填入 Embedding 模型的 Endpoint ID、AK/SK。

5. 系统模型设置：指定推理模型和 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:latest
    restart: always
    environment:
      <<: *shared-api-worker-env
      MODE: api
      UV_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:latest
    restart: always
    environment:
      <<: *shared-api-worker-env
      PYTHON_ENV_INIT_TIMEOUT: 600
      PIP_MIRROR_URL: https://mirrors.aliyun.com/pypi/simple/
      # 其他原有环境变量不变，保留即可

结尾

本文完整覆盖了国内环境下 Dify 对接火山方舟的全流程，从插件安装避坑、模型部署到智能体验证，每一步均有详细操作和代码片段，新手可直接照做。

如果在部署过程中遇到其他问题，欢迎在评论区留言交流，看到会第一时间回复～

（注：文档部分内容可能由 AI 生成）