RAGFlow API 配置

先说结论:模型供应商页添加模型

登录 RAGFlow,点右上角头像,打开模型供应商。在待添加的模型里找到 OpenAI-API-Compatible 卡片,点添加模型。在弹出的对话框里,模型类型选 chat,模型名称填精确的目录 ID,Base url 填 https://api.kkaiapi.com/v1,API-Key 粘贴你的密钥,Max tokens 填模型真实的上下文规模,点确定。 然后让它真正生效:在同一个页面打开设置默认模型,把新加的模型选成默认 LLM。聊天助手、数据集问答、Agent 节点默认都会解析到这个默认值,除非单独覆盖。有一点必须在第一次跑之前知道:RAGFlow 的 Max tokens 字段默认是 512,官方自己的提示文字都警告过一个不合适的值会导致报错,填模型真实的上下文窗口是配置的一部分,不是可选的优化项。

模型类型:   chat
模型名称:   deepseek-v4-pro
Base url:   https://api.kkaiapi.com/v1
API-Key:    sk-你的kkaiapi密钥
Max tokens: 128000

然后:设置默认模型 → LLM → deepseek-v4-pro

RAGFlow 怎么把模型绑到具体工作上

RAGFlow(GitHub 上的 infiniflow,约 8.5 万星标)是一个深度文档 RAG 引擎:对 PDF 和表格做版式感知的解析,带引用溯源的切片,再往上是数据集、聊天助手、Agent 工作流。管线里不同环节绑定不同的模型槽位,而且绑定是显式的。 Chat 模型负责生成答案,Embedding 模型负责把切片向量化用于检索,Rerank 模型负责重排候选结果,img2txt 模型在解析时负责描述图表。OpenAI-API-Compatible 供应商可以分别给这些类型注册模型,每个添加模型对话框创建一条类型、ID、Base url、Key 的绑定。每个注册过的 chat 模型都往 Base url 发标准 chat completions 请求,Model name 就是线路上的字符串,所以网关提供的任何 ID 都是有效的,不分厂商。 这个划分在实际运维上很关键:把回答模型从 gpt-5.5 换成 claude-sonnet-5,随便哪天都是安全的,但 Embedding 模型是焊死在你已建索引的向量上的。RAGFlow 对已有切片的数据集切换 Embedding 模型时会做兼容性检查,实际规则很简单:Embedding 配置定一次就不要动,Chat 模型才是可以自由调的那一层。

一个 Key,国产模型和海外模型一起用

RAGFlow 的部署天然偏中文场景:国内团队处理中英混排的文档库,海外团队又特别想要国产模型来处理中文文档。分别直连的话这种混搭很痛苦,DeepSeek、智谱、月之暗面、阿里各自计费,免翻墙直连才能稳定访问 Claude、GPT。 经一个 OpenAI-API-Compatible 的 Base url,这种混搭只是多加几个添加模型对话框:deepseek-v4-pro 和 glm-5.2 处理中文为主的语料,qwen3.7-max 和 kimi-k2.6 作为强力的区域备选,claude-sonnet-5 用在回答质量最重要的地方。同一个 Base url、同一个 Key,ID 直接从目录里抄。 还有一条首次启动就能用上的路径:docker/service_conf.yaml.template 里接受一个 user_default_llm 块(factory、api_key、base_url),让全新安装直接带着预配置起来。RAGFlow 文档明确说过,登录之后配置只能在模型供应商页面做,所以把这份 YAML 当成首次启动的预置手段,而不是实时配置。

user_default_llm:
  factory: OpenAI-API-Compatible
  api_key: sk-你的kkaiapi密钥
  base_url: https://api.kkaiapi.com/v1

给文档管线选模型

检索质量决定了答案的上限,回答模型决定你能多接近这个上限,所以在真实语料上做 A/B:同一个数据集、同一批问题,两个助手各绑一个 ID,对着 kkaiapi 控制台里每个模型的花费和自己对答案的判断一起看。

• 基于检索片段的溯源式回答是输入密集的工作,中端模型表现很好:deepseek-v4-pro 和 glm-5.2 在中英混排语料上跟得住带引用的回答
• qwen3.7-max 和 kimi-k2.6 是值得测试的区域重量级选手,答案要求原生中文表达的场景尤其明显,中文模型之间的质量差异在生成环节比检索环节更明显
• claude-sonnet-5 适合放在答案槽位,当合成质量本身就是产品的时候:执行摘要、合同分析,任何一份人会不经修改直接转发的内容
• 需要调用工具的 Agent 工作流对函数调用的可靠性要求高,先在 claude-sonnet-5 上测通 Agent 路径,再看哪个区域模型能跟上
• Max tokens 是按注册条目生效的,如果一个助手需要长回答、另一个需要收紧,同一个 ID 注册两次、给不同限额就行

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

RAGFlow 专属的翻车点

Max tokens 默认值是经典坑。留在 512 上,长回答会以看起来像模型问题的方式被截断或报错,注册模型时按文档提示填真实的上下文规模。 一个注册后立刻报错的模型,通常是模型名称拼写问题(必须和 /v1/models 列表精确一致),或者 Base url 漏了 /v1 后缀,因为 RAGFlow 会在你填的地址后面拼接路径。 注册之后没反应是默认值的问题:注册模型不等于选中模型。检查设置默认模型,也检查每个助手自己的模型设置,它会覆盖工作区默认值。 Embedding 的混乱排在最后。如果通过兼容供应商绑定一个 Embedding ID,先确认端点真的提供这个模型再开始建索引;一旦数据集已有切片,更换它的 Embedding 模型会被相似度检查拦住,可能需要从零重建索引。Chat 模型的更换没有这个代价,这正是应该在 Chat 层做实验的原因。

验证接入与排查首次对话

先 curl 一遍模型列表,Model name 字段是自由文本,直接从列表里复制 ID 能在问题发生前排除最常见的失败。然后对着计划注册的 ID 跑一次聊天补全。 在 RAGFlow 里,注册模型、设成默认 LLM,先在一个普通聊天助手里测通,再牵扯数据集。鉴权错误对应 API-Key;找不到模型对应模型名称;连接错误对应 Base url 或容器出网,因为要连到端点的是 RAGFlow 服务端,不是你的浏览器。长回答被截断或报错对应回 Max tokens。 对话跑通之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。RAG 流量是输入主导的,用量日志能看清你的语料每天、每个模型的查询实际花了多少钱,国产模型和海外模型的花费在同一页里看得清清楚楚。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer sk-你的kkaiapi密钥" | head -50

curl -s https://api.kkaiapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的kkaiapi密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"ping"}]}'

常见问题