11｜知识库 POC 实证：RAGFlow v1.0.0-rc2 本地部署与 API 验证

一句话：知识底座从开题（10 篇）走到 POC 实证——RAGFlow v1.0.0-rc2 单机全栈容器化起栈、模型供应（tokenplan chat + 本地 bge-m3 embedding）配置完成、知识库 API 小样本链路（建库 → 上传 → 解析 → 检索 → 问答）实机跑通；统一入口网关、权限模型与水平扩展仍为设计稿。状态：⚠️ POC 实机（本机 Windows + Docker Desktop，2026-10-25）；不是生产验证，不代表质量/隔离/HA 达标前置：10 篇选型定稿（RAGFlow）；本部署在 gitee 镜像仓库 + 华为云 swr 拉取链下完成。

一、部署实证：RAGFlow v1.0.0-rc2 单机 Docker 起栈

1.1 镜像获取链（国内环境完整解法）

环节	结果	结论
GitHub 直连 / 两个镜像站	全部不通	弃用
gitee.com/infiniflow/ragflow（分支 v1.0.0-rc2）	✅ 成功	源码仓库走 gitee
docker hub 直连	不通	写 mirror 解决
Docker daemon.json 5 个 mirror（壹 ms.run / daocloud / 玄元 / hub.rat.dev / 1panel.live）	✅ 生效	普通镜像走 mirror
RAGFlow 主镜像	✅ 成功	`.env` 指定华为云 swr：`RAGFLOW_IMAGE=swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v1.0.0-rc2`
ES 8.11.3 官方镜像（5 个源全试）	❌ 全部拉不动（1ms.run 缓存损坏、daocloud exit 1、1panel 卡死）	决策：DOC_ENGINE=infinity（infiniflow 同厂引擎，`infiniflow/infinity:v0.7.4-x64-v3` 经 mirror 成功）

关键决策：ES 拉不动 → 切 Infinity 向量引擎（RAGFlow 同厂，混合检索能力对标 ES，社区版 Apache-2.0）。这不是降级，是与 RAGFlow 深度集成的原生引擎选择。

1.2 起栈命令与容器清单

bash

cd D:\build\ragflow\docker
docker compose --profile infinity --profile cpu --profile metadata-mysql up -d

6 容器全 healthy：

容器	端口	角色
docker-ragflow-cpu-1	80/443/9380/9381	API Server(9380) + Admin Server(9381) + Web(80)
docker-infinity-1	23817/23820/5432	向量引擎（doc_engine）
docker-minio-1	9000/9001	对象存储（文档/切片/图片）
docker-nats-1	4222/8222	消息队列（异步任务）
docker-mysql-1	3306	元数据（数据集/文档/用户）
docker-kvrocks-1	6379	缓存（Redis 兼容）

bash

# 健康检查（全绿）
curl http://localhost:9380/api/v1/system/healthz
# {"db":"ok","redis":"ok","doc_engine":"ok","storage":"ok","message_queue":"ok"}

1.3 登录与认证（v1.0.0-rc2 与旧版差异）

路由差异：旧路径 /api/v1/healthz、/v1/user/login 在 Go 版全部 404；新路径：

面	路径	说明
API	`GET /api/v1/system/healthz`	健康检查
API	`POST /api/v1/auth/login`	用户登录
API	`POST /api/v1/users`	用户注册
Admin	`POST /api/v1/admin/login`	仅 superuser

认证机制：登录响应无 token 字段，靠响应头 Authorization: <signed> + Set-Cookie: ragflow_auth=<signed>; Max-Age=604800; SameSite=Lax；后续请求带 Authorization: Bearer <signed>。

密码协议：DB 存 werkzeug hash（pbkdf2:sha256:600000 或 scrypt），且以 base64(password) 为输入；登录 JSON 密码需传 base64；另有 RSA 加密（解密失败回退明文）。

bash

# 登录（password 传 base64；示例值必须从 Secret/环境变量读取，禁止写入文档或仓库）
curl -X POST http://localhost:9380/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"<RAGFLOW_EMAIL>","password":"<BASE64_PASSWORD_FROM_SECRET>"}'
# 响应头：Authorization: <signed> + Set-Cookie: ragflow_auth=<signed>

生产注意：POC 中曾用直改 MySQL 重置 superuser 密码，该做法不可复用。生产环境走 Secret 注入的初始化任务或受控运维流程，禁止直改库、禁止把口令写进命令历史。示例中的邮箱、密码、API Key、Token 一律用占位符。

二、模型供应实证（对标百炼 Key 一环）

2.1 Provider 池：80+ 供应商开箱

GET /api/v1/providers?available=true 返回 80+ 供应商（OpenAI / Tongyi-Qianwen / Ollama / DeepSeek / VolcEngine / Gemini / SILICONFLOW 等）。CE 版 Admin EE provider API 不支持（'list model providers' is not supported），模型配置走用户级 provider 池：

bash

# 1) 添加 OpenAI provider 到租户
curl -X PUT http://localhost:9380/api/v1/providers \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"provider_name":"OpenAI"}'

# 2) 创建两个实例（chat 与 embedding 分开的 base_url）
curl -X POST http://localhost:9380/api/v1/providers/OpenAI/instances \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"instance_name":"tokenplan","base_url":"https://token-plan.maas.qianwenaiapi.com/compatible-mode/v1","api_key":"<BUILDER_MODEL_API_KEY>"}'

curl -X POST http://localhost:9380/api/v1/providers/OpenAI/instances \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"instance_name":"local-emb","base_url":"http://host.docker.internal:9005/v1","api_key":"local"}'

# 3) 实例下添加模型
curl -X POST http://localhost:9380/api/v1/providers/OpenAI/instances/tokenplan/models \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"model_name":"qwen3.8-max","model_type":["chat"],"max_tokens":32768}'

curl -X POST http://localhost:9380/api/v1/providers/OpenAI/instances/local-emb/models \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"model_name":"BAAI/bge-m3","model_type":["embedding"],"max_tokens":8192}'

三段式模型引用（llm_id）：模型名@实例名@供应商，例如 qwen3.8-max@tokenplan@OpenAI、BAAI/bge-m3@local-emb@OpenAI——Chat/数据集全部用这个引用。

2.2 embedding 本地化（受控内网接入，不得绕过 SSRF）

弃用路线：Ollama 镜像（默认源/1ms.run/daocloud）全部拉不动；DashScope 兼容端用 tokenplan key 无效（该 key 仅 token-plan 端点可用）→ 自建 OpenAI 兼容 embedding 服务。

实证发现：RAGFlow 有 SSRF 防护（internal/utility/ssrf.go，私网地址一律拒绝）：

POST /api/v1/embeddings
{"provider_name":"OpenAI","instance_name":"local-emb","model_name":"BAAI/bge-m3","texts":["x"],"dimension":1024}
→ {"code":500,"message":"Post \"http://host.docker.internal:9005/v1/embeddings\": URL resolves to a non-public address (192.168.65.254), which is not allowed"}

该护栏是正确的安全边界，不是待绕过的障碍。POC 中 OpenAI factory 驱动会拒绝 host.docker.internal；Builtin（TEI）驱动当前走 GetSchemeSafeHTTPClient，未做同等 SSRF 校验。这里只能记录为“POC 临时接入路径”，不能作为生产方案：

生产应使用显式允许清单：只允许受控的 embedding 服务域名/地址，拒绝任意用户可控 URL；
通过出站代理统一出口，代理侧做目标校验与审计；K8s 用 NetworkPolicy 限制 RAGFlow 仅能访问允许的 embedding 与依赖；
解析 DNS 后校验实际 IP，防 DNS rebinding；禁止跟随任意重定向到私网；
向 RAGFlow 上游提交 issue/PR，推动 Builtin 驱动复用同一 SSRF 校验；在修复前使用经安全评审的内部代理或允许清单补丁，并保留变更记录。

POC 采用 @Builtin + 自建 TEI 兼容服务，仅用于验证链路可行性；上线前必须把上述护栏补齐，并通过“恶意 URL 被拒绝”的负向测试。

自建 TEI 兼容 embedding 服务（D:\build\emb-service\server.py）：

python

from fastapi import FastAPI
from pydantic import BaseModel
from sentence_transformers import SentenceTransformer
import numpy as np, uvicorn

app = FastAPI()
_model = None

def get_model():
    global _model
    if _model is None:
        _model = SentenceTransformer("BAAI/bge-m3", device="cpu")
    return _model

# OpenAI 兼容面（RAGFlow OpenAI factory 直连）
@app.post("/v1/embeddings")
async def embeddings(req: EmbedRequest):
    emb = get_model().encode(req.input if isinstance(req.input, list) else [req.input],
                             normalize_embeddings=True)
    return {"object": "list", "data": [
        {"object": "embedding", "index": i, "embedding": e.tolist()} for i, e in enumerate(emb)
    ]}

# TEI 兼容面（RAGFlow @Builtin 驱动调用 {base}/embed，返回纯 2D 数组）
@app.post("/embed")
async def tei_embed(req: TeiRequest):
    emb = get_model().encode(req.inputs if isinstance(req.inputs, list) else [req.inputs],
                             normalize_embeddings=True)
    return np.asarray(emb, dtype="float32").tolist()

bash

# 启动（9005 端口；模型走 hf-mirror 下载成功）
$env:HF_ENDPOINT="https://hf-mirror.com"
D:\build\emb-service\.venv\Scripts\python D:\build\emb-service\server.py

# 直连验证：返回 1024 维向量
curl -X POST http://localhost:9005/v1/embeddings \
  -H "Content-Type: application/json" -d '{"model":"BAAI/bge-m3","input":"hello ragflow"}'
# TEI 面
curl -X POST http://localhost:9005/embed \
  -H "Content-Type: application/json" -d '{"inputs":["hello ragflow","知识库测试"]}'

RAGFlow 侧接线（POC 三处，缺一不可；生产以安全评审后的配置为准）：

位置	修改	作用
`docker/service_conf.yaml.template`	`user_default_llm.default_models.embedding_model.base_url: 'http://${TEI_HOST}:9005'`	默认 embedding 指向本地服务
`docker/.env`	`TEI_HOST=host.docker.internal`	容器内访问宿主
`docker/docker-compose.yml`（ragflow-cpu environment）	`TEI_BASE_URL=http://host.docker.internal:9005`	@Builtin 驱动优先读 TEI_BASE_URL（否则回落 `http://<TEI_HOST>:80` → 宿主 nginx 405）

踩坑记录：只改 service_conf 不够——数据集指定 BAAI/bge-m3@Builtin 后驱动用 TEI_BASE_URL（无则 http://TEI_HOST:80），而宿主 Windows 80 端口有 nginx → 解析时报 builtin embeddings API error: status 405。加 TEI_BASE_URL 环境变量后即通。该记录只说明 POC 接线，不证明 @Builtin 的 SSRF 行为可接受。

2.3 模型验证

bash

# 租户模型列表（含 provider/instance 元数据）
GET /api/v1/models
# [{"name":"BAAI/bge-m3","model_type":["embedding"],"provider_name":"OpenAI","instance_name":"local-emb"}, ...]
# {"name":"qwen3.8-max","model_type":["chat"],"provider_name":"OpenAI","instance_name":"tokenplan"}

三、知识库 API 小样本实证（建库 → 上传 → 解析 → 检索 → 问答）

3.1 小样本链路证据（POC 实机，不代表质量达标）

证据分级：本文把证据分为四层——① endpoint exists（路由存在）；② 调用成功（HTTP/业务码成功）；③ 权限隔离通过（负向测试）；④ 计量/审计可查。当前仅完成 ①/② 的小样本验证，③/④ 未完成。

步骤	请求	结果
建库	`POST /api/v1/datasets`	✅ code=0，dataset_id=11e3f02c...，embedding=BAAI/bge-m3@Builtin
上传文档	`POST /api/v1/datasets/{id}/documents`（multipart file）	✅ doc_id=f170aadb...，ingestion_status=UNSTART
触发解析	`POST /api/v1/datasets/{id}/documents/parse`	✅ success_count=1（异步 ingestor）
解析完成	`GET /api/v1/datasets/{id}/documents`	⚠️ COMPLETED，但仅 chunk_count=4 / token_count=193，样本过小，不能证明解析质量
混合检索	`POST /api/v1/datasets/{id}/search`	⚠️ 命中目标 chunk（similarity=0.213）；只能证明双路调用成功，不能证明召回质量
RAG 问答	`POST /api/v1/chat/completions`	✅ 基于知识库内容作答（引用溯源 ID 标注）

bash

# ① 建库（注意 parse_type=1 + parser_id 必填）
curl -X POST http://localhost:9380/api/v1/datasets \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"name":"企业知识库","embedding_model":"BAAI/bge-m3@Builtin","language":"Chinese","permission":"me","parse_type":1,"parser_id":"general","parser_config":{"chunk_token_num":512,"delimiter":"\n\n"}}'

# ② 上传文档（multipart）
curl -X POST http://localhost:9380/api/v1/datasets/$DS_ID/documents \
  -H "Authorization: Bearer $AUTH" \
  -F "file=@test_doc.md;filename=test_doc.md"

# ③ 触发解析（异步）
curl -X POST http://localhost:9380/api/v1/datasets/$DS_ID/documents/parse \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d "{\"document_ids\":[\"$DOC_ID\"]}"

# ④ 混合检索（hybrid = 向量 + BM25 并行召回）
curl -X POST http://localhost:9380/api/v1/datasets/$DS_ID/search \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"question":"统一入口网关提供什么能力？","retrieval_setting":{"search_method":"hybrid","top_k":3,"similarity_threshold":0.2,"vector_similarity_weight":0.3,"rerank_id":""}}'

# ⑤ RAG 问答（检索增强生成，tokenplan qwen3.8-max）
curl -X POST http://localhost:9380/api/v1/chat/completions \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"chat_id":"$CHAT_ID","question":"统一入口网关提供什么能力？","stream":false}'

RAG 问答实测应答（答案引用知识库内容，非模型自由发挥）：

"根据知识库中的内容，统一入口网关提供以下能力：
SSO 身份接入 [ID:0]
路由转发 [ID:0]
权限拦截 [ID:0]
限流防护 [ID:0]
审计轨迹 [ID:0] 此外，统一入口网关是企业智能体平台的统一流量入口 [ID:0]。"

3.2 Chat 应用（对标百炼应用发布）

bash

# 创建 Chat（绑数据集 + 模型）
curl -X POST http://localhost:9380/api/v1/chats \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"name":"企业知识库问答","dataset_ids":["$DS_ID"],"llm_id":"qwen3.8-max@tokenplan@OpenAI","prompt_config":{}}'
# → chat_id=e526abb0...

# 问答（RAG 检索增强）
curl -X POST http://localhost:9380/api/v1/chat/completions \
  -H "Authorization: Bearer $AUTH" -H "Content-Type: application/json" \
  -d '{"chat_id":"$CHAT_ID","question":"...","stream":false}'

# OpenAI 兼容面（包皮关键：统一入口网关可直接透传 OpenAI 格式）
POST /api/v1/openai/$CHAT_ID/chat/completions

3.3 API 面存在性核对（不是全链可用证明）

除知识库核心链路外，v1.0.0-rc2 还暴露以下 API 面。“路由存在”不等于“已调用成功”，更不等于“权限/计量可用”：

能力域	路径	说明
API Key	`GET/POST/DELETE /api/v1/system/tokens`、`/system/keys`	路由存在；签发、吊销、配额未做负向验证
Chat 通道	`POST /api/v1/chat-channels`	Chat 应用发布对外
检索	`POST /api/v1/retrieval`	跨库检索
搜索	`POST /api/v1/searches`、`/searches/{id}/completions`	Search 应用（对标百炼搜索应用）
Agent	`/api/v1/agents`、`/api/v1/tasks`	Agent 编排
MCP	`POST /api/v1/mcp/servers`	MCP 管理面路由存在；对外工具面、鉴权、传输未实测
Connector	`POST /api/v1/connectors`	连接器管理（OAuth 回调链）
Langfuse	`POST /api/v1/langfuse/api-key`	路由存在；未验证追踪数据实际落库
Dify 兼容	`GET/POST /api/v1/dify/retrieval`	Dify 检索协议兼容面
统计	`GET /api/v1/system/stats/{chat,group,model}`	用量统计
技能	`/api/v1/skills`（search/index）	Skill Space
记忆	`/api/v1/memories`、`/api/v1/messages`	记忆/消息

四、统一入口网关包皮设计（#25）

4.1 包皮目标

企业智能体平台的统一入口网关对知识库侧提供四条通道（用户流量一律网关；平台流量控制面直连）：

通道	消费者	形态
知识问答	员工（Web/IM）	网关 → `/api/v1/openai/{chat_id}/chat/completions`（OpenAI 兼容）
知识检索	Agent（Skill/MCP 市场消费）	网关 → `/api/v1/retrieval` 或数据集 search
知识库管理	管理员	网关（角色白名单）→ `/api/v1/datasets` CRUD
模型/Key 管理	平台控制面	控制面直连（RT/内部）

4.2 网关对接点（复用 08 专栏统一入口网关 10 项能力）

网关能力	知识库侧落点
SSO 身份接入	网关验证 OIDC/JWT 后派生 `tenant_id/subject_id/consumer_id`；不信任请求体或下游自报的 `user_id`
Credential Broker	RAGFlow `Authorization` 由平台服务账号或短期令牌注入；员工/Agent 不持有 RAGFlow Key，凭证不落日志
角色权限层	员工 → 问答/检索白名单；管理员 → 数据集管理；管理端点在网关按平台角色拦截
限流防护	按用户/租户限流（借 RAGFlow `ToggleChat` 频控）
审计轨迹	身份 → Chat/数据集 → 请求全链路记录
SSE 流式适配	OpenAI 兼容面 SSE 转发（打字机效果，Connection keep-alive）

4.3 包皮最小改造点

凭证中介，不下发 RAGFlow Key：用户/Agent 只持有平台 Consumer 凭证；Credential Broker 用服务账号或短期令牌访问 RAGFlow。禁止“每用户签发 RAGFlow API Key 并直接下发”，否则员工可绕过网关直连引擎。
OpenAI 兼容透传：网关在固定 Chat 应用与固定数据集范围内透传 OpenAI Chat Completions 协议；请求中的 chat_id/dataset_ids 必须与授权范围匹配，不能让客户端自由切换。
检索即服务：/api/v1/retrieval 不直接暴露给客户端，由 Knowledge Broker 包装为稳定 MCP 工具（knowledge_search / secure_answer），再经 HiMarket 上架。
租户与 ACL 前置：Broker 在调用 RAGFlow 前完成订阅、工具白名单、文档 ACL 与密级校验；RAGFlow 的 me/team/public 只作为存储层兜底。

五、权限模型设计（#26，对标百炼 Workspace）

原则：租户级空间 + Knowledge Broker ACL + 服务端过滤。 不默认“每用户一个 RAGFlow 租户”，也不把 me/team/public 直接当企业权限模型。

关键机制与生产约束：

机制	POC 观察	生产口径
租户隔离	注册会生成个人租户（tenant 与 user 绑定）	`tenant_id` 由 Portal/Consumer 的已签名上下文派生；RAGFlow tenant 只作存储隔离，不是企业授权边界
数据集权限	`permission: me / team / public`	RAGFlow ACL 仅作兜底；企业 ACL 在 Broker 维护，检索时必须注入 `tenant/project/document/classification` 过滤
操作级权限	CheckAccess（OperationRun/Write）	管理端点由 Higress 按平台角色拦截，并用 NetworkPolicy 禁止客户端直达 RAGFlow 管理面
Token	`system/tokens` 可签发 RAGFlow Key	用户/Agent 只拿平台 Consumer 凭证；Broker 用服务账号或短期令牌访问 RAGFlow，Key 不下发
OIDC 贯通	可注册/登录	必须完成 ID Token JWK 验签；`user_id`、`tenant_id` 等自报字段只作断言，不一致拒绝
空间模型	小样本单 Dataset	按租户/项目建空间；共享文档与私有文档分别授权；删除与撤权需可验证传播

上线前必须通过的负向测试：跨租户访问、同租户不同角色、共享/私有文档、伪造 dataset_ids、撤销订阅后调用、绕过网关直连 RAGFlow 内部接口。仅“建第二个 Portal 能隔离”不够。

六、水平扩展分析（#27，对标百炼高并发）

6.1 RAGFlow 微服务架构可扩展点

组件	扩展方式	说明
api_server	多副本 + 负载均衡	无状态（会话在 MySQL/Kvrocks/Infinity）
ingestor	多 worker 横向扩	解析/向量化任务队列（NATS）分发
doc_engine（Infinity）	Infinity 集群 / 分片	向量索引水平扩展
MySQL	主从/读写分离	元数据
MinIO	分布式 MinIO	对象存储
NATS	集群	任务队列

6.2 K8s 部署形态（生产建议）

先纠正一个常见误判：POC 镜像默认同时运行 api_server 与 ingestor；同一镜像拆成两个 Deployment 不会自动分成两种角色。必须以官方 Helm/Compose 的 entrypoint/command、角色参数与共享存储约定为准。下面的 YAML 只是字段示意，不可直接复制上线；没有官方支持时，优先按官方 chart 部署，再按实测瓶颈扩容。

yaml

# 示意 only：command/args 必须来自官方 chart 或已评审的启动脚本
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ragflow-api
spec:
  replicas: 2
  selector: { matchLabels: { app: ragflow-api } }
  template:
    metadata: { labels: { app: ragflow-api } }
    spec:
      containers:
        - name: ragflow-api
          image: swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v1.0.0-rc2
          command: ["<OFFICIAL_API_ENTRYPOINT>"]   # 待按官方实现确认
          envFrom:
            - configMapRef: { name: ragflow-conf }
            - secretRef: { name: ragflow-secret }
          env:
            - name: TEI_BASE_URL
              value: "http://emb-service:9005"
          volumeMounts:
            - { name: ragflow-data, mountPath: /ragflow/data }
          readinessProbe:
            httpGet: { path: /api/v1/system/healthz, port: 9380 }
            initialDelaySeconds: 30
          resources:
            requests: { cpu: "2", memory: "8Gi" }
            limits:   { cpu: "4", memory: "16Gi" }
      volumes:
        - name: ragflow-data
          persistentVolumeClaim: { claimName: ragflow-data }
---
# ingestor：必须确认官方支持的独立启动方式；不支持时不要强行拆
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ragflow-ingestor
spec:
  replicas: 1
  selector: { matchLabels: { app: ragflow-ingestor } }
  template:
    metadata: { labels: { app: ragflow-ingestor } }
    spec:
      containers:
        - name: ragflow-ingestor
          image: swr.cn-north-4.myhuaweicloud.com/infiniflow/ragflow:v1.0.0-rc2
          command: ["<OFFICIAL_INGESTOR_ENTRYPOINT>"]  # 待确认

生产还必须补齐：

共享状态：MySQL、Infinity、MinIO、Kvrocks、NATS 均需独立高可用部署；api 副本不得使用本地盘保存状态；
探针与生命周期：liveness/readiness/startup 探针、优雅停机、PDB、HPA 指标（CPU/队列积压/检索 P95）；
网络与凭证：NetworkPolicy 限制客户端只能访问 Higress；RAGFlow 管理面与内部端口不对用户网段开放；Secret 由 Vault/KMS 注入；
数据保护：Infinity/MySQL/MinIO 备份与恢复演练，RPO/RTO 需实测；
容量结论：只有完成并发压测与故障演练后才能给出 QPS/容量结论；当前没有证据证明“与百炼对齐”。

七、对标百炼能力表（POC 证据状态）

状态含义：✅ 已实机验证；⚠️ 仅小样本验证、不能外推；⏳ 仅端点/参数存在；❌ 未验证。没有一项达到生产验收。

#	百炼能力	RAGFlow POC 状态	证据与限制
RAG-1	知识库管理 + 智能切片	⚠️ 建库 + GeneralChunker 成功	仅 1 个 Markdown 小样本，chunk_count=4 / 193 tokens，不能代表企业文档
RAG-2	混合检索（向量+BM25）	⚠️ hybrid 调用成功	命中 1 条 chunk、similarity=0.213；无黄金集、无 recall@k，不能证明召回质量
RAG-3	Rerank + Query 改写	⏳ 引擎有参数位	Rerank 未接入、未对照；Query 改写未验证
RAG-4	问答 API + 引用溯源	⚠️ 单次问答成功	只有 [ID:0] 引用，未验证引用正确率、无答案拒答与防泄漏
API-Key	独立访问密钥	⏳ 路由存在	未验证签发/吊销/配额；生产不下发 RAGFlow Key 给员工
Connector	统一连接层 MCP	⏳ MCP 管理面路由存在	未验证实际工具清单、鉴权、Streamable HTTP 与调用闭环
Memory	记忆库	⏳ `/api/v1/memories` 路由存在	未验证隔离、删除、审计；详见 12 篇
ParseX	多格式解析	⏳ 仅 Markdown 小样本	PDF/表格/扫描件/OCR 均未实证，不能宣称 DeepDoc 链路已通过
观测	Langfuse 追踪	⏳ 路由存在	未验证追踪落库、查询与保留策略

八、实证台账（POC / 生产缺口）

能力	状态	证据与说明
6 容器全栈起栈（Go v1.0.0-rc2）	✅ POC	本机 Docker，healthz 全绿；单机非 HA
镜像获取链（gitee + 华为云 swr + mirror）	✅ POC	见 1.1；镜像 digest 需在交付物中固定
DOC_ENGINE=infinity 决策	✅ POC	ES 拉取失败后的替代；未做容量/故障对比
登录/认证（base64 密码 + Bearer）	✅ POC	登录成功；凭据已改为占位符，禁止入库
provider 池 + 双实例 + 三段式 llm_id	✅ POC	tokenplan / local-emb
本地 embedding（bge-m3 + TEI 兼容）	⚠️ POC	9005 /embed 直连与解析调用成功，但依赖 `@Builtin` 临时路径
受控内网 embedding 接入	⚠️ 未完成	不能写“SSRF 绕过成功”；允许清单、出站代理、NetworkPolicy、DNS rebinding 防护均未实现
建库/上传/解析	⚠️ POC	COMPLETED，但仅 4 chunks / 193 tokens
混合检索	⚠️ POC	命中 1 条 chunk；无黄金集与阈值
RAG 问答（检索增强生成）	⚠️ POC	单次问答有引用；未验证正确率/防泄漏
OpenAI 兼容问答面	⏳ 端点	路由存在，未做协议兼容回归
API Key / Chat Channels / Langfuse / Dify	⏳ 端点	路由存在，未调用验证
Rerank 精排	❌ 未实证	需 bge-reranker 或 qwen3-rerank 接入并做 A/B
Connector 同步（OAuth 链）	❌ 未实证	`/connectors` 路由存在，OAuth 回调与同步未跑
记忆/技能（#21/#28 联动）	❌ 未实证	`/memories` `/skills` 路由存在，隔离/删除/审计未验证
跨租户与文档 ACL 负向测试	❌ 未执行	必须覆盖跨租户、同租户角色、共享/私有、伪造 dataset_id、撤订、旁路直连
质量基线（黄金集）	❌ 未执行	recall@k、MRR、引用正确率、无答案拒答率、越权率
删除/撤权传播	❌ 未执行	向量、缓存、引用快照的删除完成状态
HA / 容量 / 灾备	❌ 未执行	并发压测、节点故障、备份恢复、RPO/RTO
计量 / 审计	❌ 未闭环	网关权威事件未接入；RAGFlow 日志不能作为计量源

生产边界（如实记录）：本实证是 v1.0.0-rc2 单机 Docker POC。生产至少还需：K8s 化与 HA（见第六章）、embedding 服务的受控内网接入与 SSRF 护栏、OIDC JWK 验签、Knowledge Broker ACL 与负向测试、黄金集质量基线、删除/撤权传播、网关计量与审计落库、备份恢复演练。在这些完成前，不得表述为“生产可用”或“全链闭环”。

11｜知识库 POC 实证：RAGFlow v1.0.0-rc2 本地部署与 API 验证 ​

一、部署实证：RAGFlow v1.0.0-rc2 单机 Docker 起栈 ​

1.1 镜像获取链（国内环境完整解法） ​

1.2 起栈命令与容器清单 ​

1.3 登录与认证（v1.0.0-rc2 与旧版差异） ​

二、模型供应实证（对标百炼 Key 一环） ​

2.1 Provider 池：80+ 供应商开箱 ​

2.2 embedding 本地化（受控内网接入，不得绕过 SSRF） ​

2.3 模型验证 ​

三、知识库 API 小样本实证（建库 → 上传 → 解析 → 检索 → 问答） ​

3.1 小样本链路证据（POC 实机，不代表质量达标） ​

3.2 Chat 应用（对标百炼应用发布） ​

3.3 API 面存在性核对（不是全链可用证明） ​

四、统一入口网关包皮设计（#25） ​

4.1 包皮目标 ​

4.2 网关对接点（复用 08 专栏统一入口网关 10 项能力） ​

4.3 包皮最小改造点 ​

五、权限模型设计（#26，对标百炼 Workspace） ​

六、水平扩展分析（#27，对标百炼高并发） ​

6.1 RAGFlow 微服务架构可扩展点 ​

6.2 K8s 部署形态（生产建议） ​

七、对标百炼能力表（POC 证据状态） ​

八、实证台账（POC / 生产缺口） ​

11｜知识库 POC 实证：RAGFlow v1.0.0-rc2 本地部署与 API 验证

一、部署实证：RAGFlow v1.0.0-rc2 单机 Docker 起栈

1.1 镜像获取链（国内环境完整解法）

1.2 起栈命令与容器清单

1.3 登录与认证（v1.0.0-rc2 与旧版差异）

二、模型供应实证（对标百炼 Key 一环）

2.1 Provider 池：80+ 供应商开箱

2.2 embedding 本地化（受控内网接入，不得绕过 SSRF）

2.3 模型验证

三、知识库 API 小样本实证（建库 → 上传 → 解析 → 检索 → 问答）

3.1 小样本链路证据（POC 实机，不代表质量达标）

3.2 Chat 应用（对标百炼应用发布）

3.3 API 面存在性核对（不是全链可用证明）

四、统一入口网关包皮设计（#25）

4.1 包皮目标

4.2 网关对接点（复用 08 专栏统一入口网关 10 项能力）

4.3 包皮最小改造点

五、权限模型设计（#26，对标百炼 Workspace）

六、水平扩展分析（#27，对标百炼高并发）

6.1 RAGFlow 微服务架构可扩展点

6.2 K8s 部署形态（生产建议）

七、对标百炼能力表（POC 证据状态）

八、实证台账（POC / 生产缺口）