1. 先搞清楚这条链路的真正价值：从本地模型到可用的文档问答

如果你手头有本地部署的大语言模型，比如通过 Ollama、LM Studio 或者 vLLM 跑起来的 Llama、Qwen 等，那么你肯定想过怎么把它用起来。直接调 API 写脚本是最直接的，但想做个带界面的、能上传文档、能持续对话的问答应用，从头开发太费劲。

这时候，像 Dify 和 扣子（Coze） 这类 AI 应用平台 的价值就出来了。它们不是模型，而是“引擎”和“组装车间”。这条链路的核心价值是： 把你本地的模型能力，快速封装成一个具备知识库检索增强（RAG）能力的、可交互的智能应用，而无需从零构建前端、后端和复杂的 RAG 流水线。

很多人会混淆几个概念：

• 本地模型 ：提供最底层的文本理解和生成能力，是你的“计算引擎”。
• Dify/扣子 ：是“应用组装平台”。它们提供可视化的工作流编排、知识库管理、对话界面、API 发布等功能。它们需要接入一个模型（可以是云端的如 GPT-4，也可以是你本地的）才能工作。
• RAG（检索增强生成） ：是一种技术方案，不是具体工具。它通过在生成答案前，先从你的文档（知识库）里检索相关信息，让模型基于这些信息回答，减少“胡言乱语”。Dify 和扣子都内置了实现 RAG 的整套流程（文本切分、向量化、检索、提示词组装）。
• 文档问答 ：是 RAG 技术最典型的应用场景。

所以，完整链路是： 本地模型（能力源） → 通过 API 暴露给 Dify/扣子（应用组装平台）→ 在平台上配置知识库和 RAG 工作流 → 生成一个可用的文档问答 Agent 或 Web 应用。

这条链路解决了什么实际问题？它让算法工程师或开发者能聚焦在模型本身，而将应用层复杂的工程问题（前后端、数据管道、交互逻辑）交给专业平台，极大降低了 AI 应用的原型验证和交付门槛。

2. 环境与核心组件准备：模型、平台与连接桥

在开始“组装”之前，你需要确保几个核心组件就位。这就像修车，得先把发动机、底盘、电路准备好。

2.1 本地模型部署与 API 暴露

这是链路的起点。你的模型必须能以 OpenAI API 兼容 的格式提供服务。这是 Dify 和扣子能接入的前提。

常见方案与选择：

1. Ollama ：最适合新手和快速原型。它管理模型下载、运行，并直接提供兼容 OpenAI 的 API 端点。

   • 安装 ：官网下载安装，一条命令拉取模型，如 ollama pull qwen2.5:7b 。
   • 运行与 API ：运行 ollama run qwen2.5:7b 后，默认会在 http://localhost:11434 提供 API。关键是要使用其 /v1 兼容端点，例如聊天接口是 http://localhost:11434/v1/chat/completions 。
   • 优点 ：开箱即用，无需复杂配置。
   • 注意 ：性能并非最优，适合本地开发和小规模测试。

2. vLLM ：追求高吞吐量和低延迟的生产级选择。它专为高效服务大模型设计。

   • 安装 ： pip install vllm
   • 运行与 API ：启动命令类似 python -m vllm.entrypoints.openai.api_server --model Qwen/Qwen2.5-7B-Instruct --served-model-name qwen2.5-7b 。它会启动一个服务，默认端口为 8000 ，API 格式与 OpenAI 完全兼容（如 http://localhost:8000/v1/chat/completions ）。
   • 优点 ：支持连续批处理、PagedAttention 等优化，并发性能好。
   • 注意 ：配置相对复杂，对 GPU 环境要求更严格。

3. LM Studio ：图形化界面友好的本地工具，也提供本地 API。

   • 安装 ：直接下载桌面客户端。
   • 运行与 API ：在软件内加载模型后，开启“本地服务器”功能，会提供一个 API 端点（如 http://localhost:1234/v1/chat/completions ）。
   • 优点 ：完全图形化操作，对不熟悉命令行的用户友好。
   • 注意 ：相比前两者，其底层性能和资源调度控制粒度较粗。

验证模型 API 是否就绪： 无论用哪种方式，部署后第一件事就是用 curl 或 Python 脚本测试接口是否通畅。

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5:7b",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 50
  }'

如果收到包含 "content" 的 JSON 响应，说明模型服务正常。

2.2 AI 应用平台选择：Dify 与扣子对比

两个平台都能完成我们的目标，但侧重点不同。

特性	Dify	扣子 (Coze)
核心定位	开源、可自托管的 AI 应用开发平台，强调工作流编排和 API 化。	字节跳动出品的在线 AI Bot 创建平台，更偏向于快速创建和分发对话型 Agent。
部署方式	支持 Docker 一键本地/服务器部署 ，数据完全私有。	仅限云端 SaaS 服务 ，数据存储在平台。
自定义程度	高。可深度定制工作流、前端界面、后端逻辑。	中。提供丰富的插件和预设能力，但平台限定内的组合。
知识库/RAG	功能强大，支持多种文本分割器、向量数据库（Milvus, PGVector等）可选，处理流程透明可控。	功能集成化，开箱即用，但底层细节（如切分策略、向量库）对用户黑盒。
接入本地模型	原生支持 。在模型供应商设置中直接填入你的本地 API Base URL 和模型名称即可。	间接支持 。官方不直接支持。通常需要通过 云函数/自定义插件 或 API 网关转发 的方式，将请求代理到你的本地服务，有一定技术门槛。
适合场景	企业级应用、需要私有化部署、深度定制 RAG 流程、将 AI 能力作为 API 集成到现有系统。	个人或团队快速搭建一个功能丰富的对话机器人，并发布到飞书、微信等平台，对数据隐私要求不高。

对于“本地模型 → 平台”这个核心诉求，Dify 是更直接、更简单的选择。 下文将主要以 Dify 为例进行演示，因为它与本地模型的集成路径最短、最清晰。扣子的方案会作为补充思路提及。

2.3 基础环境检查清单

在动手前，快速过一遍这个清单：

• 硬件 ：确保你的机器（尤其是 GPU 内存）能同时跑起 本地模型服务 和 Dify 服务 。例如，运行一个 7B 模型可能需要 8-10GB GPU 显存，Dify 本身还会占用一些 CPU 和内存。
• 网络 ：本地服务间通过 localhost 通信，确保防火墙没有阻止相关端口（如 11434, 8000, 3000, 5000）。
• 软件 ：安装好 Docker 和 Docker Compose（用于部署 Dify），以及 Python/pip（用于可能需要的测试脚本或 vLLM）。
• 模型文件 ：提前下载好你打算使用的模型文件，避免部署时因网络问题中断。

3. 实战：在 Dify 中接入本地模型并构建 RAG 应用

我们假设你已经用 Ollama 在 localhost:11434 跑起了一个 qwen2.5:7b 模型。现在目标是让 Dify 使用这个模型来驱动一个知识库问答应用。

3.1 部署 Dify

使用 Docker Compose 部署是最推荐的方式，能一次性启动所有依赖（前端、后端、数据库）。

# 1. 克隆仓库（或下载 docker-compose.yml）
git clone https://github.com/langgenius/dify.git
cd dify/docker

# 2. 启动所有服务
docker-compose up -d

启动后，访问 http://localhost:3000 就能看到 Dify 的 Web 界面。首次进入需要创建管理员账号。

3.2 关键一步：配置本地模型

这是连接链路的核心。

1. 进入模型配置 ：在 Dify 控制台，点击左侧菜单栏的“模型供应商” -> “模型”。
2. 添加自定义模型 ：点击“添加模型”，在供应商类型里选择 “OpenAI-Compatible” 。
3. 填写配置信息 ：
   • 模型名称 ：自定义一个名字，如 My-Local-Qwen 。
   • 模型类型 ：选择“文本生成”或“对话”（根据你的模型能力）。
   • 模型 ID ：填写你的本地模型在 API 调用时使用的名称。 对于 Ollama，这个名称就是你拉取模型时用的名字，如 qwen2.5:7b 。对于 vLLM，是 --served-model-name 指定的名字。
   • API Base URL ：填写你的本地模型服务地址， 务必包含 /v1 路径 。例如 Ollama 是 http://host.docker.internal:11434/v1 。这里注意：
     • 如果 Dify 和模型都在同一台机器的 Docker 中运行，需使用 http://host.docker.internal:端口 来从容器内访问宿主机服务。
     • 如果 Dify 通过 docker-compose 部署，模型进程直接跑在宿主机，就用 http://host.docker.internal:11434/v1 。
     • 如果都是宿主机进程，则用 http://localhost:11434/v1 。
   • API Key ：本地模型通常不需要，可以留空或随意填写（如 sk-xxx ）。
4. 测试连接 ：保存后，Dify 会提供测试功能。发送一个简单的测试提示词，如“你好”，看是否能收到模型返回的响应。 测试成功，才证明链路打通了。

踩坑点 ：90% 的连接问题都出在 API Base URL 和 模型 ID 上。一定要确保 URL 能从容器的网络环境访问到，且模型 ID 与模型服务端识别的名称一致。可以用 curl 先在 Dify 所在的容器网络环境内测试一下这个 API 地址。

3.3 构建 RAG 知识库问答应用

模型接入后，剩下的工作都在 Dify 的可视化界面中完成。

1. 创建应用 ：点击“创建应用”，选择“对话型应用”，命名为“我的本地知识库助手”。
2. 配置模型 ：在应用编排界面，左侧“提示词”或“工作流”区域，找到模型选择器。你应该能看到刚刚添加的 My-Local-Qwen ，选中它。
3. 创建并配置知识库 ：
   • 点击左侧“知识库”菜单，创建新的知识库，如“产品手册”。
   • 进入知识库，点击“上传文件”，支持 PDF、Word、TXT、Markdown 等格式。Dify 会后台自动进行：
     • 文本提取 ：从文件中读取文字。
     • 文本分割 ：将长文本按策略（如按段落、按固定长度）切分成片段（Chunks）。
     • 向量化 ：使用嵌入模型（Embedding Model）将每个文本片段转换为向量。这里需要注意： Dify 默认使用云端的嵌入模型（如 OpenAI text-embedding-3-small） 。如果你追求全链路本地化，需要在“设置”->“模型供应商”中配置本地的嵌入模型（例如通过 http://localhost:11434/v1/embeddings 接入 Ollama 的嵌入模型，或部署专门的 BGE 模型服务）。
     • 存储 ：向量会被存储在你配置的向量数据库中（Dify 默认使用内置的向量存储）。
4. 在应用中使用知识库 ：
   • 回到你的应用编排界面。
   • 在“提示词”编排模式中，你可以勾选“上下文”下的“知识库”，并选择你刚创建的“产品手册”。
   • 更灵活的方式是使用“工作流”模式。拖入一个“知识库检索”节点，连接到你的“LLM”节点之前。这样，用户问题会先经过知识库检索，将相关片段作为上下文注入给模型，模型再生成答案。
5. 优化提示词 ：在提示词框中，你可以设计系统指令，例如：

   你是一个专业的客服助手，请严格根据提供的上下文信息回答问题。
   上下文信息如下：
   {context}
   
   用户问题：{query}
   
   如果上下文信息不足以回答问题，请如实告知“根据现有资料无法回答该问题”，不要编造信息。
   

   Dify 会自动将 {context} 和 {query} 替换为实际内容。

3.4 测试、发布与集成

1. 对话测试 ：在应用界面的右侧预览窗格，直接提问。观察：
   • 答案是否基于你上传的文档内容？
   • 模型响应速度如何？
   • 如果答案不准，是检索的问题（调整知识库的分割规则、检索 top-k 值），还是模型理解的问题（优化提示词）？
2. 发布 ：测试满意后，点击“发布”。你可以获得：
   • Web 访问链接 ：一个独立的 H5 页面，可分享给他人。
   • API 端点 ：用于集成到你的其他系统。Dify 会为你生成标准的 Chat Completion API。
3. 监控与迭代 ：在 Dify 的“日志与标注”中，可以查看每一次对话的详细过程（检索到的片段、发送给模型的完整提示词、模型回复），这是优化 RAG 效果最重要的依据。

4. 扣子（Coze）平台的接入思路与差异处理

如果你更倾向于使用扣子，由于它不直接支持填入本地 API，需要“曲线救国”。

核心思路：创建一个“中间层”代理，将扣子的请求转发到你的本地模型服务。

4.1 方案一：使用云函数/自定义插件

1. 编写代理服务 ：你需要在一个扣子能访问的公网服务器上（或使用 Serverless 云函数），部署一个简单的 HTTP 服务。这个服务接收扣子插件格式的请求，然后将其转换为 OpenAI 兼容格式，调用你的本地模型 API（ 这里需要解决公网访问内网模型的问题，可以使用内网穿透工具如 ngrok，或部署在同一个内网环境的服务器上 ），再将结果转换回扣子需要的格式返回。
2. 在扣子中创建自定义插件 ：将你的代理服务地址配置为插件后端。
3. 在 Bot 中使用插件 ：创建 Bot 时，添加你这个自定义插件作为“模型”或“工具”。

优点 ：灵活性最高，可以完全控制逻辑。 缺点 ：技术门槛高，涉及服务部署、网络打通、协议转换，且存在内网模型暴露的安全风险。

4.2 方案二：利用 API 网关或反向代理

如果你有一个具有公网 IP 的服务器，可以在上面部署 Nginx 等反向代理，将特定路径的请求转发到你内网的模型服务。然后在扣子的自定义插件中，直接调用这个反向代理的公网地址。

优点 ：相对云函数方案，架构更简单直接。 缺点 ：同样需要公网服务器和配置网络，安全策略需要格外注意。

对比与建议 ： 对于“本地模型+扣子”这个组合，除非你有很强的需求必须使用扣子的特定插件或发布渠道，否则其实现复杂度远高于 Dify 。 Dify 的开源和可私有化部署特性，使其与本地模型的结合是原生、顺畅的。 扣子更适合直接使用平台提供的云端模型（如豆包大模型、GPT等）快速构建应用。

5. 效果调优与生产化考量

链路跑通只是第一步。要让这个文档问答应用真正可用，还需要关注以下几个层面。

5.1 RAG 效果优化：不止是接上就行

RAG 的效果 = 检索质量 + 模型理解与生成质量。模型固定后，优化重点在检索。

1. 文本分割策略 ：Dify 知识库设置中的“分段处理”规则至关重要。

   • 按段落/标题分割 ：适合结构清晰的文档（如 Markdown、HTML），能保持语义完整性。
   • 固定长度分割 ：通用性强，但可能切断完整句子或概念。建议设置合理的重叠长度（如 100-200 字符），让相邻片段有信息交叉。
   • 实践 ：上传同一份文档，用不同分割方式测试几个典型问题的答案质量。

2. 检索参数 ：

   • Top-k ：每次检索返回多少个文本片段。太小可能遗漏信息，太大会引入噪声并增加模型处理负担。一般从 3-5 开始调整。
   • Score Threshold ：相关性分数阈值，低于此值的片段不返回。可以过滤掉低质量检索结果。
   • 检索方式 ：Dify 支持关键词检索、向量检索和混合检索。对于专业领域， 混合检索 （结合关键词匹配和语义相似度）通常效果更鲁棒。

3. 提示词工程 ：

   • 明确指令模型“基于上下文回答”。
   • 在上下文中加入明确的引用标记（如 【来源1】... ），并指令模型在回答中注明出处。
   • 对于模型“幻觉”（编造），可以在提示词中加强约束：“如果上下文未提供相关信息，请直接说‘我不知道’”。

5.2 性能、稳定性与成本

1. 响应延迟 ：本地模型的推理速度是主要瓶颈。在 Dify 应用发布设置中，注意配置合理的 API 超时时间 ，避免前端长时间等待。对于慢模型，可以考虑在 UI 上增加“正在思考”的加载状态。
2. 并发与吞吐 ：vLLM 在这方面优于 Ollama。如果预期有多个并发用户，需要使用 vLLM 并调整其 --max-num-batched-tokens 、 --tensor-parallel-size 等参数，同时确保硬件资源充足。
3. 知识库更新 ：文档更新后，需要在 Dify 知识库中手动或通过 API 触发“重新索引”，这是一个计算密集型操作。对于大型知识库，建议在业务低峰期进行。
4. 成本 ：全链路本地化，成本主要是电费和硬件折旧。需要监控 GPU 利用率，根据实际负载考虑服务启停策略。

5.3 扩展：从对话应用到工作流

Dify 的“工作流”模式能力更强。你可以构建复杂的多步骤应用：

• 检索后处理 ：在检索结果送给模型前，先经过一个“代码解释器”节点进行数据提取或总结。
• 多知识库路由 ：根据用户问题类型，自动选择不同的知识库进行检索。
• 工具调用 ：结合 Dify 的“工具”功能，让模型在回答时不仅能查知识库，还能调用外部 API（如查询天气、计算数据）。

6. 常见问题排查清单

当你的应用不工作时，按照这个顺序排查：

1. 模型服务本身是否正常？

   • 在终端直接用 curl 测试模型 API，看是否返回有效结果。
   • 检查模型服务日志，是否有加载错误或 OOM（内存不足）报错。

2. Dify 到模型的网络是否通畅？

   • 进入 Dify 的后端容器内部： docker exec -it dify-api bash 。
   • 在容器内使用 curl 测试你配置的 API Base URL 。 这是最关键的排查步骤 ，很多问题是因为 Docker 容器网络导致的。

3. Dify 模型配置是否正确？

   • API Base URL 是否以 /v1 结尾？
   • 模型 ID 是否与模型服务端注册的名称完全一致（大小写敏感）？
   • 在 Dify 的“模型供应商”设置页面，使用“测试”功能，看错误信息。

4. 知识库检索是否生效？

   • 在应用的“日志与标注”中，查看具体某次对话的详情。
   • 检查“知识库检索”节点是否输出了片段？这些片段是否与问题相关？
   • 如果不相关，调整知识库的分割规则或检索的 top-k 值。

5. 提示词是否合理？

   • 在日志详情中，查看最终发送给模型的完整提示词（ messages ）。检查 {context} 是否被正确替换？系统指令是否清晰？

6. 资源是否耗尽？

   • 使用 nvidia-smi 和 htop 查看 GPU 显存和 CPU/内存使用情况。同时运行模型服务和 Dify 可能吃满资源。

这条从本地模型到 RAG 应用的链路，其价值在于 工程上的整合效率 。它把复杂的 AI 应用开发，变成了在可视化平台上“连接管线”和“配置参数”的工作。对于中小型团队或个人开发者，这能节省数月的前后端开发时间。真正的挑战不在于连接本身，而在于对每个环节（模型服务、文本分割、检索策略、提示词）的深入理解和精细调优，这决定了最终应用效果的上下限。先从 Dify + Ollama 这个最简组合跑通全流程，再逐步替换为性能更强的 vLLM，优化嵌入模型和检索参数，是风险最低、学习曲线最平滑的实践路径。