Dify 接入

Dify 是一个开源的大语言模型（LLM）应用开发平台，结合了 AI 工作流编排、RAG（检索增强生成）、Agent 智能体、模型管理等核心能力，让开发者和非技术用户都能快速构建生产级 AI 应用。

对 TokenFlash 来说，Dify 最常见的接法就是把它当作 OpenAI-API-compatible provider 来配置。一个 API Key 即可调用所有模型。

核心功能

为什么用 Dify + TokenFlash

部署 Dify

Docker Compose 部署（推荐）

前置要求： Linux 2 核 4GB+、Docker 20.10+、Docker Compose 2.0+

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
# 可选：编辑 .env 中的 SECRET_KEY、DB_PASSWORD、REDIS_PASSWORD
docker compose up -d

启动后访问 http://your-server/install 设置管理员账号。

# 验证所有容器正常运行
docker compose ps

所有容器状态应为 Up。之后访问 Dify 主界面。

Dify Cloud

如果你不想部署，可直接使用 Dify Cloud：

1. 注册账号（支持 GitHub / Google 登录）
2. 创建工作空间
3. 进入控制台

接入 TokenFlash API（核心章节）

获取 TokenFlash API Key

1. 登录 TokenFlash 控制台
2. 进入 API Keys → 创建新 Key
3. 复制并保存（创建后不再显示）

在 Dify 中添加模型

1. 点击右上角 头像 → 设置 → 模型供应商
2. 找到 OpenAI-API-compatible 并点击进入

推荐添加的模型

GPT 系列：

Claude 系列（通过 OpenAI 协议适配）：

Gemini 系列：

Embedding 模型（RAG 知识库用）：

添加时「模型类型」必须选择 Text Embedding，否则知识库向量化无法正常工作。

验证模型可用性

添加后在模型供应商页面应显示绿色"已连接"标记。也可创建测试 Chatbot 发送消息验证。

构建 AI 应用

Chatbot 应用

1. 工作室 → 创建空白应用 → 聊天助手
2. 选择刚添加的 TokenFlash 模型（如 gpt-5.6-sol）
3. 配置参数：Temperature 0.7、Max Tokens 4096
4. 编写系统提示词定义角色行为
5. 发布 并测试

Agent 应用

Agent 可以调用外部工具，具备更强的推理和执行能力：

1. 创建应用时选择 Agent 类型
2. 选择推理策略：Function Call（推荐，gpt-5.6-sol / claude-sonnet-5 均支持）
3. 在"工具"区域添加内置工具（Google Search、Wikipedia、计算器等）
4. 可关联知识库增强回答准确性

Workflow 工作流

Workflow 允许通过节点式编排实现复杂业务逻辑：

智能文档问答工作流示例：

[开始] → [知识检索] → [IF/ELSE]
  ├─ 有结果 → [模板转换] → [LLM] → [结束]
  └─ 无结果 → [LLM] → [结束（附"仅供参考"提示）]

节点间通过 {{start.query}}、{{knowledge.retrieval_result}} 等语法传递变量。

RAG 知识库配置

创建知识库

1. 左侧导航 知识库 → 创建知识库
2. 选择索引方式：高质量模式（使用 Embedding 模型，推荐）
3. 选择 text-embedding-3-small（性价比最高）

文档导入

支持 PDF、TXT、Markdown、DOCX、HTML、XLSX、CSV 等格式，单文件最大 15MB。

分段策略建议：

检索策略

推荐配置：混合检索、Top K 5、Score 阈值 0.5。

实战案例

案例一：智能客服机器人

基于公司知识库创建自动回答常见问题的客服应用：

1. 导入产品手册、FAQ、售后政策等文档创建知识库
2. 创建 Chatbot 应用，关联知识库，模型使用 claude-sonnet-5
3. 配置系统提示词限定回答范围和语气
4. 设置预设问题（开场白）引导用户

API 调用示例：

curl -X POST 'https://你的dify域名/v1/chat-messages' \
  -H 'Authorization: Bearer app-你的应用API密钥' \
  -H 'Content-Type: application/json' \
  -d '{"inputs": {}, "query": "你们的产品价格是多少？", "response_mode": "blocking", "user": "user-123"}'

案例二：多步骤工作流自动化

自动生成研究报告的工作流：

[开始] 接收主题
  ↓
[LLM-1: gpt-5.6-luna] 生成报告大纲
  ↓
[知识检索] 用大纲关键词检索知识库
  ↓
[LLM-2: gpt-5.6-sol] 基于大纲+检索结果撰写报告
  ↓
[LLM-3: claude-sonnet-5] 校对优化
  ↓
[结束] 输出最终报告

不同模型各司其职 — 轻量模型做简单任务，强模型做复杂任务，充分利用 TokenFlash 的多模型优势。

高级配置

多模型路由策略

成本分级：

速率限制

Dify 应用设置中可配置每分钟最大调用次数、每日最大 Token 消耗量。

避免触发 429 的建议：降低并发、实现重试机制。

日志与监控

• Dify 内置 日志与标注 页面查看对话记录、Token 消耗、响应延迟
• Docker 日志：docker compose logs -f api
• 可集成 Prometheus + Grafana 监控 API 延迟、错误率、Token 消耗速率

常见问题

模型添加后无法使用

排查：

# 测试 API 连通性
curl -I https://tokenflash.cn/v1/models

# 测试模型调用
curl -X POST https://tokenflash.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}]}'

# 检查 Dify 日志
docker compose logs api | grep -i error

常见原因：API Key 错误、模型名称拼写错误、Endpoint URL 缺少 /v1、账户余额不足。

API 连接超时

• 检查 Dify 服务器到 https://tokenflash.cn/v1 的网络连接
• 增加超时：.env 中设置 MODEL_REQUEST_TIMEOUT=120，重启服务
• 配置代理：.env 中设置 HTTP_PROXY 和 HTTPS_PROXY

Embedding 模型不可用

确认模型类型选择了 Text Embedding（非 LLM），且验证状态为"已连接"。切换 Embedding 模型后需要创建新知识库并重新向量化。

上下文长度设置

上下文并非越大越好，过大会增加 Token 消耗和响应延迟。

与官方 API 的差异

快速配置速查

OpenAI 协议 Base URL: https://tokenflash.cn/v1
Dify 通道:            OpenAI-API-compatible
API Key:              你的 TokenFlash API Key

推荐模型:
  LLM:       gpt-5.6-sol / gpt-5.6-terra / claude-sonnet-5
  Embedding: text-embedding-3-small
  Gemini:    gemini-3.5-flash / gemini-3.1-pro-high

参考资源

1. Dify 官方文档
2. Dify GitHub
3. TokenFlash 文档站