RAGFlow 实战(二):0.26.2 接 OpenAI-compatible 网关,embedding 解析失败与 Dataset API 调用

这是「RAGFlow 实战」系列的第二篇。第一篇会先讲 RAGFlow 是什么、适合什么场景、以及几种部署方式；这一篇只处理落地时很容易卡住的一段链路：RAGFlow 0.26.2 接 OpenAI-compatible 模型网关，以及 Dataset 解析阶段的 embedding 失败。

问题现象很直接：页面上 LLM 验证通过了，Chat 也能发起请求，但一上传文件做 Dataset 解析就失败，报错集中在 embedding：

Fail to bind embedding model
Embedding request failed for OpenAIEmbed
Error: 'NoneType' object is not iterable

这篇只记录一个实操问题：RAGFlow 0.26.2 怎么接一个 OpenAI-compatible 风格的模型网关，以及 Dataset 解析失败时如何确认是不是 embedding endpoint 配错了。

下面的域名、Key、Provider 实例名、模型别名、网关路径和资源 ID 都做了占位处理，照抄时换成你自己的环境。

环境

项目	值
RAGFlow	0.26.2
访问入口	`https://<ragflow-domain>`
模型网关	`https://<model-gateway-domain>`
RAGFlow Provider	OpenAI
LLM	`<CHAT_MODEL>`
Embedding	`text-embedding-3-small`
Dataset 解析方式	Built-in / General

先给结论：RAGFlow 的 Provider Base-Url 要填到公共前缀，不要填完整的 /chat/completions 或 /embeddings。

这次网关最终可用的形态是：

Base-Url: https://<model-gateway-domain>/<gateway-api-prefix>
LLM:      <CHAT_MODEL>
Embedding:text-embedding-3-small

RAGFlow 会自己在 Base-Url 后面拼：

/chat/completions
/embeddings

如果你把 Base-Url 填成 .../chat/completions，LLM 验证可能过，但 Dataset 解析时 RAGFlow 再去拼 embedding 路径就会出错。

这条链路里最容易填错的是第 ② 步：Provider 的 Base-Url 只填公共前缀。第 ③ 步和第 ④ 步的具体 endpoint 由 RAGFlow 按调用类型自动追加。

一、先确认网关有没有 embedding 接口

不要先在 RAGFlow 页面里反复点 Verify。先用 curl 直接测 embedding。

这类模型网关文档通常会给两个等价路径。这里用 <gateway-api-prefix> 代表你的网关 API 前缀：

/<gateway-api-prefix>/embedding
/<gateway-api-prefix>/embeddings

实测用复数路径即可：

curl -X POST 'https://<model-gateway-domain>/<gateway-api-prefix>/embeddings' \
  -H 'Authorization: Bearer <MODEL_GATEWAY_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text-embedding-3-small",
    "input": "hello"
  }'

成功响应里必须有 data[0].embedding：

{
  "data": [
    {
      "embedding": [0.0167, -0.0557, 0.0056],
      "index": 0
    }
  ]
}

如果你请求的是标准 OpenAI 路径：

curl -X POST 'https://<model-gateway-domain>/v1/embeddings' ...

{"code":404,"code_msg":"router not found","resp_data":null}

那说明这个网关没有暴露标准 /v1/embeddings，不能按标准 OpenAI 根路径配置。

还有一个常见误区：不要把文档页面当 API 请求地址。例如这种地址一般只是文档页：

https://<docs-domain>/api-reference/<embedding-doc-path>

对它 POST 会得到：

Method Not Allowed

这不是 Key 错，而是你请求了文档页面。

二、RAGFlow 里 Provider 怎么填

进入：

User settings -> Model providers

选择 OpenAI Provider，新增或编辑实例：

Instance name: <PROVIDER_INSTANCE>
API-Key:       <MODEL_GATEWAY_API_KEY>
Base-Url:      https://<model-gateway-domain>/<gateway-api-prefix>

注意 Base-Url 停在网关 API 公共前缀。不要填成：

https://<model-gateway-domain>/<gateway-api-prefix>/chat/completions
https://<model-gateway-domain>/<gateway-api-prefix>/embeddings
https://<model-gateway-domain>/v1

前三种分别会导致：

错误填法	结果
填完整 chat endpoint	LLM 可能通，embedding 解析失败
填完整 embeddings endpoint	Chat 路径拼错
填 `/v1`	网关没有 `/v1/embeddings` 时直接 404

Provider 验证通过只说明当前表单能连上某类接口，不代表 Dataset 解析一定能过。Dataset 解析必须单独验证 embedding。

三、默认模型怎么选

进入：

User settings -> Model providers -> Set default models

最小配置：

LLM       -> <CHAT_MODEL> <PROVIDER_INSTANCE>
Embedding -> text-embedding-3-small <PROVIDER_INSTANCE>
VLM       -> 空
ASR       -> 空
Rerank    -> 空
TTS       -> 空

普通 RAG 知识库只需要 LLM 和 Embedding。

text-embedding-3-small 足够做默认测试：成本低、速度快，先把链路跑通。text-embedding-3-large 可以留到检索质量不够时再换。

四、创建 Dataset 并验证解析

创建 Dataset 时这样填：

Name:            dataset-test
Embedding model: text-embedding-3-small <PROVIDER_INSTANCE>
Parse type:      Built-in
Built-in:        General

上传一个小文件后，看文件列表里的状态。

失败时通常会看到：

Status: Failed
Chunks: 0

Fail to bind embedding model
Embedding request failed for OpenAIEmbed
Error: 'NoneType' object is not iterable

这时不要先怀疑文件格式，先回到第一步测 embedding curl。

成功时应该看到：

Status: Success
Chunks: 1

Task has been received.
Start to parse.
Finish parsing.
Generate 1 chunks.
Embedding chunks.
Indexing done.
Task done.

Chunks > 0 才说明 Dataset 里已经有可检索片段。

五、Chat 必须绑定 Dataset

RAGFlow 顶部的 Multiple models 更像普通模型对话，不等于绑定了知识库。只在里面问：

总结一下 _payload.json 的内容

如果 Chat app 没绑定 Dataset，就会返回：

The answer you are looking for is not found in the dataset!

正确做法是在 Chat 页面创建 Chat app，并绑定刚才的 Dataset。

API 也能直接确认：

curl -sS 'https://<ragflow-domain>/api/v1/chats?page=1&page_size=30' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' | jq

绑定前：

{
  "dataset_ids": [],
  "kb_names": []
}

绑定后：

{
  "dataset_ids": ["<DATASET_ID>"],
  "kb_names": ["dataset-test"]
}

这一步很关键。chat_id 不是 Dataset id，也不是左侧对话记录 id，而是 Chat app 的 id。

六、API 调用

先在 RAGFlow 的：

User settings -> API

创建 RAGFlow API Key。这个 Key 是 RAGFlow 的，不是模型网关的 Key。

查 Dataset

curl -sS 'https://<ragflow-domain>/api/v1/datasets?page=1&page_size=30' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' | jq

查 Chat app

curl -sS 'https://<ragflow-domain>/api/v1/chats?page=1&page_size=30' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' | jq

确认返回里有：

id          -> 作为 chat_id
dataset_ids -> 非空
kb_names     -> 有目标 Dataset 名称

OpenAI-compatible Chat Completions

curl -sS -X POST \
  'https://<ragflow-domain>/api/v1/openai/<CHAT_ID>/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' \
  -d '{
    "model": "<CHAT_MODEL>@<PROVIDER_INSTANCE>@OpenAI",
    "messages": [
      {"role": "user", "content": "总结一下上传文件的内容"}
    ],
    "stream": false,
    "extra_body": {
      "reference": true
    }
  }' | jq

如果要做流式返回，把 stream 改成 true，客户端按 SSE 处理。

只测检索，不走 LLM

curl -sS -X POST 'https://<ragflow-domain>/api/v1/retrieval' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' \
  -d '{
    "question": "payload",
    "dataset_ids": ["<DATASET_ID>"],
    "page": 1,
    "page_size": 5,
    "similarity_threshold": 0.2,
    "vector_similarity_weight": 0.3,
    "top_k": 10
  }' | jq

如果 retrieval 能召回 chunk，但 Chat 仍然答不出来，优先检查 Chat app 是否绑定 Dataset、相似度阈值是否过高、prompt 里是否强制“只基于知识库回答”。

七、故障对照表

现象	最可能原因	处理
`Method Not Allowed`	请求了文档页面，不是 API 地址	换成实际模型网关域名
`/v1/embeddings` 返回 `router not found`	模型网关不支持标准 `/v1` embedding	用文档给的 `/<gateway-api-prefix>/embeddings`
LLM Verify 通过，但 Dataset 解析失败	Base-Url 填到了 chat endpoint	Base-Url 改成公共前缀
`Chunks = 0`	没有成功生成索引	看文件详情里的解析日志
Chat 返回 `not found in the dataset`	Chat app 未绑定 Dataset，或检索没命中	查 `/api/v1/chats` 的 `dataset_ids`
`/api/v1/chats` 返回空	当前 API Key 所属用户下没有 Chat app	页面创建 Chat app 或检查 API Key 所属账号

这张动图按排查顺序走：先独立验证 embedding，再回到 RAGFlow 配 Provider、默认模型和 Dataset，最后用 Chat app 的 dataset_ids 与 API 调用确认链路闭合。

快速参考

RAGFlow Provider：

Provider:  OpenAI
Base-Url:  https://<model-gateway-domain>/<gateway-api-prefix>
LLM:       <CHAT_MODEL>
Embedding: text-embedding-3-small

Embedding 自测：

curl -X POST 'https://<model-gateway-domain>/<gateway-api-prefix>/embeddings' \
  -H 'Authorization: Bearer <MODEL_GATEWAY_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"model":"text-embedding-3-small","input":"hello"}'

RAGFlow Chat API：

curl -sS -X POST \
  'https://<ragflow-domain>/api/v1/openai/<CHAT_ID>/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <RAGFLOW_API_KEY>' \
  -d '{
    "model": "<CHAT_MODEL>@<PROVIDER_INSTANCE>@OpenAI",
    "messages": [{"role": "user", "content": "总结一下上传文件"}],
    "stream": false,
    "extra_body": {"reference": true}
  }'

三条判断标准：

Dataset 文件详情里 Status = Success 且 Chunks > 0，说明解析和 embedding 成功。
/api/v1/chats 里 dataset_ids 非空，说明 Chat app 已绑定知识库。
retrieval 能召回 chunk，Chat 才有机会基于知识库回答。

posted @ 2026-06-30 21:23 Hello_worlds 阅读(26) 评论(0) 收藏举报

刷新页面返回顶部

大军军军之技术落地

责人之心责己、恕己之心恕人