# 通过 OpenAI-API-Compatible 提供商把 RAGFlow 接到 Router One

> https://router.one/zh/integrations/ragflow 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-20

RAGFlow 是 InfiniFlow 开源的 RAG 引擎：DeepDoc 把文档解析、切分进知识库，聊天助手、搜索和 Agent 画布再基于知识库作答。这些功能都需要一个 LLM，而 RAGFlow 的 OpenAI-API-Compatible 提供商发送的是 Chat Completions 请求，所以一把 Router One Key 就能填上 LLM 这个位置（模型支持图片输入时还能填 VLM），目录里的聊天模型任选，每次请求在 Dashboard → Logs 都有成本 Trace。Embedding、Rerank、ASR 和 TTS 这几个位置要留给其他提供商或本地模型，因为 Router One 只提供聊天接口。本指南基于 RAGFlow v0.27.2 编写，它的模型设置从 v0.27.0 起改为按提供商实例管理。下面依次讲实例表单、每个模型的 Max tokens 与 Tool call、设置默认模型，以及哪些知识库和聊天选项会成倍放大模型请求。

## 用 Docker 启动 RAGFlow，并创建专用 Key

官方快速开始面向 x86 主机：至少 4 核 CPU、16 GB 内存、50 GB 磁盘，Docker 24.0.0 及以上、Docker Compose v2.26.1 及以上。Elasticsearch 要求 vm.max_map_count 不低于 262144，首次启动前先设好，并写进 /etc/sysctl.conf 以便重启后仍然生效。克隆仓库、切到发布标签，然后在 docker 目录里启动整套服务；下面就是快速开始里的原命令。等 docker logs 里出现 RAGFlow 的启动横幅，再在浏览器打开 http://IP_OF_YOUR_MACHINE，Web 界面默认监听 80 端口。Router One 是公网 HTTPS 端点，这里用不到 host.docker.internal 之类的地址：RAGFlow 容器只要能向外访问 api.router.one 的 HTTPS 即可。在 Router One 为这套部署单独创建一把 Key 并设置 maxSpend，因为 RAGFlow 的每个解析任务、每轮对话、每一步 Agent 调用，用的都是提供商实例里保存的这一把 Key。

`terminal`

```bash
# Elasticsearch 需要这个值；写进 /etc/sysctl.conf 才能长期生效
sudo sysctl -w vm.max_map_count=262144
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker
git checkout -f v0.27.2
docker compose -f docker-compose.yml up -d
# 看到 RAGFlow 启动横幅后再登录
docker logs -f docker-ragflow-cpu-1
```

## 把 RAGFlow 配置到 Router One base URL

打开「用户设置」→「模型提供商」，在「可选模型」里选 OpenAI-API-Compatible，填写新实例卡片；下方代码块按顺序列出了它的字段。「实例名称」（Instance name）只是这组凭据的标签，除了 'default' 会被后端拒绝，其他名字都可以。「基础 URL」（Base URL）填 https://api.router.one/v1：提供商把它交给官方 openai Python SDK，由 SDK 拼接 /chat/completions，所以每次聊天请求都是 POST /v1/chat/completions。从 v0.27.0 起，源码里的 ensure_v1 会在 URL 不含版本段时补上 /v1，更早的版本则原样使用你填的值，所以无论哪个版本都应填带 /v1 的形式；不要把完整的 /chat/completions 路径贴进去。API Key 填 Router One Key。在「模型」区域，「模型列表」（List models）会向网关的 /v1/models 拉取目录，点 + 则打开「添加自定义模型」（Add custom model）单独加一个 ID。「模型名称」必须是目录里的精确 ID：RAGFlow 内部把引用拼成 model@instance@provider，只按 @ 拆分，提供商类也只会去掉 ___ 后缀，所以像 anthropic/claude-sonnet-5 这样带斜杠的 ID 会原样写进请求的 model 字段。「模型类型」选 Chat。「最大 Token 数」（Max tokens）在源码里是上下文预算，尽管官方配置文档把它写成生成上限：RAGFlow 把它存为模型的 max_length，检索到的切片最多填到它的 97%，消息列表会被裁剪到它的 95%，填 0 时回退为 8192，并且会把 max_tokens 从发出的请求里删掉，所以这里应填模型详情页上的上下文窗口。只有模型详情页列出工具调用时才打开 Tool call。点「保存」时 RAGFlow 会真实发一次测试对话（流式的一句 'Hi'），只要有一个模型应答就保存实例；然后打开「设置默认模型」选择 LLM：

`ragflow-model-provider`

```text
# RAGFlow v0.27+ → 用户设置 → 模型提供商 → 可选模型 → OpenAI-API-Compatible
# RAGFlow v0.27+ → User settings → Model providers → Available models → OpenAI-API-Compatible
实例名称（Instance name）:     router-one   # 不能叫 default / anything except 'default'
基础 URL（Base URL）:          https://api.router.one/v1
API Key:                       sk-your-router-one-key

# 模型（Models）→ 模型列表（List models），或点 + 添加自定义模型（Add custom model）
模型名称（Model name）:        <exact-model-id-from-/models>
模型类型（Model type）:        Chat   # 支持图片输入时可加选 VLM / add VLM only for image input
最大 Token 数（Max tokens）:   <context-window-from-the-model-detail-page>
模型特性（Model features）:    Tool call = on   # 仅当模型详情页列出工具调用 / only if the model page lists tool calling

# 保存（Save）→ 设置默认模型（Set default models）
LLM:                           <exact-model-id-from-/models>
Embedding / Rerank / ASR / TTS: 其他提供商或本地模型 / another provider or a local model
```

## RAGFlow 的每个字段会发出什么请求

Router One 需要的配置只有一个提供商实例，外加每个目录 ID 对应的一条模型记录。新建实例时，RAGFlow 会把「模型列表」返回的内容全部预先加入，并按名称里的关键字推断类型：Router One 的所有 ID 都会被标成 Chat，列表里如果有生图模型的 ID 也不例外，Tool call 默认关闭，Max tokens 默认 8192，除非列表响应里带有 RAGFlow 能识别的上下文字段。不用的行用减号按钮移除，不要整份保留；留下的每一行都点开「编辑模型」检查一遍：

| RAGFlow 字段或位置 | 发给 Router One 的内容 | 填什么、核对什么 |
| --- | --- | --- |
| 实例 → 基础 URL（Base URL） | 每次聊天请求都是 POST /v1/chat/completions；「模型列表」是 GET /v1/models | https://api.router.one/v1；v0.27.0 及以后会补上缺失的 /v1，更早的版本不会 |
| 实例 → API Key | 该实例发出的每个请求都带 Authorization: Bearer | 为这套部署单独创建、设了 maxSpend 的 Router One Key；保存时的测试请求会出现在 Dashboard → Logs |
| 添加自定义模型 → 模型名称（Model name） | 请求里的 model 字段，原样发送 | /models 里的精确 ID，厂商前缀也要保留；模型详情页必须列出 POST /v1/chat/completions |
| 模型类型（Model type） | Chat：Chat Completions。VLM：带 image_url 内容的 Chat Completions | 所有模型都选 Chat；只有详情页列出图片输入时才加选 VLM。不要选 Embedding 或 Rerank |
| 最大 Token 数（Max tokens） | 不会出现在请求里；它是 RAGFlow 自己给历史消息和检索切片留的上下文预算 | 模型详情页标注的上下文窗口；填 0 时回退为 8192 |
| 模型特性（Model features）→ Tool call | Agent 组件请求里的 tools 数组 | 只有详情页列出工具调用时才打开；关闭时 RAGFlow 只在日志里记一条警告，不发送任何工具 |
| 设置默认模型 → LLM | 解析阶段的请求：自动关键词提取、自动问题提取、自动元数据，每个切片各一次 | 选 Router One 的聊天模型；每个这样的请求在 Logs 里都是一行 |
| 设置默认模型 → Embedding、Rerank、ASR、TTS | 没有：Router One 没有 embeddings、rerank 和音频端点 | 其他提供商或本地模型；RAGFlow 至少要求设好默认 LLM 和默认 Embedding 模型 |

## Embedding、Rerank 和语音模型从哪里来

RAGFlow 的配置文档要求至少设两个默认模型：LLM 和 Embedding 模型，Router One 只能承担前者。从 v0.22.0 起 RAGFlow 只发布 slim 镜像，docker/.env 里也写明 v0.22+ 的镜像不含 Embedding 模型，所以要从下面三种来源里选一种。Compose 文件里自带一个可选的 text-embeddings-inference 服务：在 docker/.env 里取消注释那行给 COMPOSE_PROFILES 加上 tei-cpu（或 tei-gpu）的配置，用 TEI_MODEL 选模型（文件里列出的选项包括 BAAI/bge-m3 和 BAAI/bge-small-en-v1.5，并标了各自的内存需求），主机访问 huggingface.co 受限时再设置 HF_ENDPOINT=https://hf-mirror.com。也可以用本地推理服务：官方的本地模型指南讲了 Ollama 和 Xinference 两种接法，并以 Ollama 上的 bge-m3 作为 Embedding 模型的示例。或者从 RAGFlow 的支持模型列表里任选一家 Embedding 提供商。快速开始特别提醒：知识库一旦用某个 Embedding 模型解析过文件，就不能再更换，所以建库之前先定好。在 Router One 这个实例里，不要给任何模型选 Embedding 或 Rerank 类型：这两种类型会请求 /v1/embeddings 和 /v1/rerank，网关不提供这些端点；ASR 和 TTS 模型同样要来自提供音频接口的提供商。检索、重排和文档存储（Elasticsearch 或 Infinity）都在 RAGFlow 内部完成，只有拼好的提示词会到达 Router One。

## 给一套部署定预算：哪些操作会成倍放大模型请求

请求数涨得最快的是解析阶段。知识库配置里打开「自动关键词提取」「自动问题提取」或「自动元数据」后，任务执行器会为每个打开的选项对每个切片各调用一次 LLM：一份文档切成 2,000 个切片、开了两个选项，就是大约 4,000 次请求；RAGFlow 会按模型和切片文本缓存每次的结果。知识编译（Knowledge compilation）在 v0.27.0 取代了原来的 Knowledge graph（GraphRAG）和 RAPTOR 选项，提供 Graph、Tree、Wiki、PageIndex、MindMap、Timeline 几种模板；它使用每个模板里的 Default extraction model，按运行时配置文档，单个任务默认最多允许 20 个并发 LLM 调用（WIKI_MAP_LLM_POOL_SIZE、DOC_STRUCTURE_LLM_POOL_SIZE）。聊天助手里每轮对话是一次回答请求，「多轮对话优化」（从第二个问题开始）、「关键词分析」和「跨语言搜索」每开一项再各加一次，这三项都在助手的聊天设置里。Agent 画布上，Agent 组件每次运行至少一次请求，每一轮工具调用再加一次，上限是「最大反思轮数」（源码默认 5），「问题分类」（Categorize）组件同样会调用模型。RAGFlow 自己也会重试：聊天类对限流和服务端错误最多重试 LLM_MAX_RETRIES 次（默认 5），每一次真正到达网关的尝试都是独立的 Trace 和费用。「验证全部模型」会对列表里的每个模型真实发一次测试请求。给这套部署单独一把设了 maxSpend 的 Key，失控的解析任务会停在 HTTP 402，钱包和其他 Key 不受影响；一个提供商下可以建多个实例，所以再建一个 OpenAI-API-Compatible 实例、配另一把 Key，就能把解析和聊天的花费分开。Dashboard → Logs 才是计费依据，逐请求记录模型、tokens、成本、延迟、状态和 request_id；RAGFlow 自己对流式回复的 token 统计，在数据块不带 usage 时是本地估算的。

## RAGFlow 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 RAGFlow 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## RAGFlow 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 RAGFlow 的调用

先在 RAGFlow 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 保存时报 'Fail to access model(OpenAI-API-Compatible/…).No valid response received'，是什么意思？

这句话是 RAGFlow 自己的笼统结论，不是网关返回的内容。点「保存」或某一行的验证按钮时，RAGFlow 会向模型流式发送一句测试对话；请求出错时它会丢掉细节，只报 Fail to access model(OpenAI-API-Compatible/你的模型 ID).No valid response received；如果 10 秒内没有任何返回（验证阶段 LLM_TIMEOUT_SECONDS 的默认值），则报 Timeout accessing model(…)。真正的原因在服务端日志里：运行 docker logs -f docker-ragflow-cpu-1，找到包含 async base giving up 的那一行，里面有 HTTP 状态码和网关的错误消息。401 AUTH_INVALID_API_KEY 说明 Key 贴错了或已被撤销。404 not_found 且消息提示修正 base URL，说明路径不对：Base URL 里填了完整的 /v1/chat/completions，SDK 会再拼一次 /chat/completions；而 v0.27.0 之前的版本不会替你补上缺失的 /v1。400 且消息含 must be called via，说明这个 ID 属于别的端点，被「模型列表」标成 Chat 的生图模型 ID 就是这种情况；其他 400 则把模型名称和 /models 逐字比对，并注意测试请求带了 temperature 0.9。如果 Dashboard → Logs 里没有这次尝试的记录，先看原始响应和 RAGFlow 服务端日志，不能就此判断请求没到网关；尚待定价的记录可能暂时不展示。连接错误再检查 RAGFlow 主机向外的 HTTPS 与 DNS。在聊天助手里，同样的失败会以 ERROR 开头的回答出现，后面跟着 RAGFlow 的错误类别和网关的原始消息。

### 模型测试通过了，但解析文档时卡在 Embedding 这一步。Embedding 模型能不能也用 Router One？

不能。Router One 在 /v1/chat/completions 上提供聊天模型，没有 embeddings、rerank 和音频端点；而 RAGFlow 解析时要给每个切片做向量化，检索时要给每个问题做向量化。如果「设置默认模型」里没有 Embedding，或者选中的是 Router One 实例里被标成 Embedding 类型的模型，就会出现 LLM 测试通过、解析失败的情况。把默认 Embedding 模型设成 Compose 文件里可选的 TEI 服务（docker/.env 里的 tei-cpu 或 tei-gpu profile）、Ollama 或 Xinference 上的模型（例如 bge-m3），或另一家 Embedding 提供商；Rerank 留空，或交给提供该接口的提供商。解析任何文件之前就要选好：知识库一旦用某个 Embedding 模型解析过文件，RAGFlow 就不允许再更换。

### 我用的是 RAGFlow v0.26 或更早版本，只有一个 Add LLM 对话框，没有实例。有什么不同？

要填的值一样，只是表单不同。v0.27.0 之前的版本为 OpenAI-API-Compatible 打开的是单个对话框，字段包括 Model type、Model name、Base url、API-Key 和 Max tokens，另有 Enable tool call 和 Does it support Vision? 两个开关。Model type 选 chat，Model name 填精确的目录 ID，Base url 填 https://api.router.one/v1，Max tokens 填模型详情页上的上下文窗口；RAGFlow 界面里这个字段的说明文字就是「模型的最大上下文大小」。有两点不同。第一，base URL 会原样使用，漏了 /v1 时测试请求会发到 /chat/completions，网关返回 404 not_found。第二，RAGFlow 会用一个以 ___OpenAI-API 结尾的内部名称保存模型；提供商类在每次请求前都会去掉这个后缀，所以网关收到的仍是不带后缀的目录 ID。按发布说明，重做后的模型提供商系统随 v0.27.0 在 2026 年 8 月 19 日发布。

### RAGFlow 能通过网关用哪些模型？

选用当前目录中同时支持 RAGFlow 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- RAGFlow 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Agno 接入：https://router.one/zh/integrations/agno
- MaxKB 接入：https://router.one/zh/integrations/maxkb
- FastGPT 接入：同类的知识库平台：https://router.one/zh/integrations/fastgpt
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- Agent 组件的工具调用要求：https://router.one/zh/llm-tool-calling
- RAGFlow 官方文档：Configure Model API Key：https://ragflow.io/docs/llm_api_key_setup
- RAGFlow 官方文档：Quickstart：https://ragflow.io/docs/
- RAGFlow 官方仓库：docker/.env（Embedding 服务与镜像选项）：https://github.com/infiniflow/ragflow/blob/main/docker/.env
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/ragflow
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md