CangLu Knowledge Base

流程拆解

6分钟阅读

流程拆解

主题索引 | learn 索引

图清单

1. 直接使用者的最短上手链路

flowchart TD
    S[打开 Dify]
    P[配置模型供应商]
    C[创建一个聊天应用]
    Q[直接发起对话]
    K[接入知识库]
    W[补工作流]
    O[稳定迭代]

    S --> P
    P --> C
    C --> Q
    Q --> K
    K --> W
    W --> O

为什么这条链路最有效

  • 先配模型供应商：先验证 Dify 是否能真实调用模型。
  • 再建聊天应用：先拿到最小正反馈。
  • 再导知识库：先确认产品价值。
  • 最后加工作流：把复杂度放在后面，不要在第一步就堆逻辑。

2. 模型供应商配置的高频坑

这是直接使用阶段最值钱的部分。

2.1 OpenAI 兼容配置最常见的坑

基于本次实际核对到的插件实现，OpenAI provider 有三个高频坑：

坑一：API Base 不要自己带 /v1

源码锚点：

  • /Users/canglu/develop/docker/dify/plugin-daemon/cwd/langgenius/openai-0.3.8@592c8252795b5f75807de2d609a03196ed02596b409f7642b4a07548c7ff57ef/models/common_openai.py:23-26

插件会自动把你填的 openai_api_base 拼成：

  • <API Base>/v1

所以应当填写：

  • https://api.openai.com
  • https://你的兼容网关域名

不应填写：

  • https://api.openai.com/v1
  • https://你的兼容网关/v1

坑二：Validate Model 要填真实存在的模型

源码锚点：

  • provider/openai.py:24-27
  • models/llm/llm.py:343-416

插件会用 validate_model 去真的发一次模型请求。若填入不存在模型，会直接失败。

本次实际日志里已经出现过：

  • Base model gpt-5.5 not found

所以 validate_model 不能乱填。

坑三：超时不等于本地 Dify 坏了

本次实际日志里，validate_provider_credentials 多次耗时约 10 到 11 秒后报：

  • Request timed out.

这说明：

  • Dify 本地页面可能是正常的
  • plugin-daemon 也可能是正常的
  • 真正慢的是上游模型服务或兼容网关

2.2 最新一次更有价值的错误：401

本次后续日志还出现过：

  • authentication_error
  • invalid api key

这说明当网络和接口路径基本打通后，问题已经收敛到：

  • API Key 无效

这是很典型的排障路径：

  • 先超时
  • 再修到可达
  • 最终暴露出真实鉴权错误

3. 报错时的分层定位法

flowchart TD
    E[看到错误]
    A[先判断是页面层还是能力层]
    B[页面打不开或 502]
    C[模型保存失败]
    D[API 扩展失败]
    N[看 nginx 或访问入口]
    M[看 provider 配置与上游模型]
    X[看目标 API 本身]
    R[收敛到单一层次]

    E --> A
    A --> B
    A --> C
    A --> D
    B --> N
    C --> M
    D --> X
    N --> R
    M --> R
    X --> R

3.1 页面层问题

典型现象：

  • 502 Bad Gateway
  • 页面打不开
  • 路由访问异常

这类问题更接近：

  • nginx
  • web
  • api
  • 容器运行状态

3.2 模型供应商问题

典型现象：

  • 保存 provider 报错
  • Request timed out.
  • invalid api key
  • Base model ... not found

这类问题优先看：

  • API Base
  • API Key
  • validate_model
  • api_protocol
  • 上游兼容性

3.3 API 扩展问题

典型现象：

  • connection error
  • 404 页面 HTML
  • 某个你自己填的接口返回失败

这类问题优先看：

  • 你填的目标 URL 是否存在
  • 是不是把根路径当成业务接口了
  • 上游是否真的有该 endpoint

4. 直接使用者速查表

4.1 一开始先学什么

  • 模型供应商
  • 应用
  • 知识库
  • 工作流

4.2 一开始先别学什么

  • 容器编排
  • 源码实现
  • 插件开发
  • sandbox 细节
  • nginx 配置细节

4.3 错误含义速记

  • 502：更像入口层或 upstream 容器连接问题
  • Request timed out.：更像上游响应慢或网关卡住
  • invalid api key：通常已经打到上游，只是鉴权失败
  • model not found：模型名或校验模型填错
  • 404 HTML：很可能是你填的外部接口路径本身不对

4.4 最值钱的一条习惯

不要把“页面问题、模型问题、插件问题、API 扩展问题”混成一个问题看。

直接使用 Dify 的效率，核心不在于记住所有功能，而在于先分层，再排错。

关系图谱