RAGFlow OpenCAIO 知识库管理

将文档上传到 OpenCAIO 知识库，使用 RAGFlow API 完成上传、解析、检索全流程。

配置信息

API 端点速查

通用请求头

Authorization: Bearer ${RAGFLOW_API_KEY}
Content-Type: application/json  (检索/解析/对话)
Content-Type: multipart/form-data  (上传)

知识库分类体系（强制）

OpenCAIO 知识库采用路径文件夹结构，五层顶级目录：

skills/     → 技能定义（每个 Skill 一个子文件夹）
agents/     → Agent 配置
company/    → 公司资料
standards/  → 规范与规则
memories/   → 记忆归档

分类准入规则

skills/{skill-name}/ — 技能定义，每个 Skill 一个独立文件夹

• ✅ 完整 SKILL.md，一个文件夹一个 Skill
• ❌ 混放多个 Skill、使用记录、片段引用
• 命名: skills/{skill-name}/SKILL.md

agents/{agent-name}/ — Agent 配置

• ✅ IDENTITY/SOUL/AGENTS 完整内容、A2A协议、路由规则
• 命名: agents/{agent-name}/{文档名}_v{版本}.md

company/ — 公司资料

• ✅ 产品介绍、商业计划、组织架构
• 命名: company/{主题}_{日期}.md

standards/ — 规范规则

• ✅ 行为规范、代码规范、安全策略
• 命名: standards/{规范名}_v{版本}.md

memories/ — 记忆归档

• 命名: memories/{主题}_{日期}.md

分类检查清单

上传前必须确认：

1. ✅ 使用路径格式: {top-folder}/{sub-folder}/文件名.md
2. ✅ 一个 Skill 一个文件夹（不可混放）
3. ✅ YAML front matter 中 category 字段匹配
4. ✅ 检查是否已存在同名路径（存在则先删后传）

文档上传标准（强制）

1. 文档格式要求

2. 内容质量标准

必须满足：
✅ 有明确的标题层级（H1 → H2 → H3）
✅ 每段内容独立完整，可独立理解
✅ 关键术语首次出现时给出定义
✅ 代码块标注语言类型
✅ 无重复内容

禁止上传：
❌ 纯占位符或草稿内容
❌ 大量重复或高度相似的内容
❌ 无结构的长文本（超过 2000 字无标题分段）
❌ 包含敏感信息（密钥、密码、个人隐私）

3. 元数据标准（可选但推荐）

在 Markdown 文档顶部添加 YAML front matter：

---
title: "文档标题"
category: "product|technical|design|business|meeting"
author: "作者"
date: "YYYY-MM-DD"
tags: ["tag1", "tag2"]
version: "1.0"
---

4. 文档命名规范

标准工作流

Step 1: 准备文档

1. 确认文档符合上述内容质量标准
2. 按命名规范重命名文件
3. 检查文件编码为 UTF-8

Step 2: 上传文档

curl -X POST \
  http://8.134.103.73:12700/api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/documents \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  -F "file=@/path/to/document.md"

成功响应: {"code": 0, "data": [{...}]} — 记录返回的 id 字段作为 DOCUMENT_ID

Step 3: 解析文档

curl -X POST \
  http://8.134.103.73:12700/api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/chunks \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["DOCUMENT_ID"]}'

成功响应: {"code": 0}

Step 4: 验证解析结果

等待 3-10 秒后检查文档状态：

curl -s \
  http://8.134.103.73:12700/api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/documents \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  | python3 -c "import sys,json; [print(f'{d[\"name\"]}: run={d[\"run\"]} chunks={d.get(\"chunk_count\",0)}') for d in json.load(sys.stdin)['data']['docs']]"

验证标准：

• run = DONE
• status = 1
• chunk_count > 0

Step 5: 检索验证

curl -X POST \
  http://8.134.103.73:12700/api/v1/retrieval \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"question": "测试查询内容", "dataset_ids": ["2ccc31fe4f8511f181580bef240bdf9e"]}'

验证标准：

• 返回 chunks 非空
• similarity > 0.3
• 内容与查询相关

批量上传工作流

多文件上传时：

1. 扫描目录，过滤出符合标准的文件
2. 逐个上传（间隔 2 秒，避免触发限流）
3. 收集所有 DOCUMENT_ID
4. 一次性提交解析: {"document_ids": ["id1", "id2", ...]}
5. 等待解析完成（轮询检查，间隔 5 秒，最多等 60 秒）
6. 验证所有文档 chunk_count > 0
7. 输出报告: 成功/失败数量、失败文档及原因

批量上传脚本模板：

#!/bin/bash
SERVER="http://8.134.103.73:12700"
KEY="ragflow-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo"
DS="2ccc31fe4f8511f181580bef240bdf9e"
DIR="${1:-.}"

IDS=()
for f in "$DIR"/*.md; do
  [ -f "$f" ] || continue
  echo "📤 $f"
  RESP=$(curl -s -X POST "$SERVER/api/v1/datasets/$DS/documents" \
    -H "Authorization: Bearer ${RAGFLOW_API_KEY}" -F "file=@$f")
  ID=$(echo "$RESP" | python3 -c "import sys,json; print(json.load(sys.stdin)['data'][0]['id'])" 2>/dev/null)
  if [ -n "$ID" ]; then
    IDS+=("\"$ID\"")
    echo "  ✅ $ID"
  else
    echo "  ❌ 失败: $RESP"
  fi
  sleep 2
done

if [ ${#IDS[@]} -gt 0 ]; then
  ID_LIST=$(IFS=,; echo "${IDS[*]}")
  echo "🔧 解析 ${#IDS[@]} 个文档..."
  curl -s -X POST "$SERVER/api/v1/datasets/$DS/chunks" \
    -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
    -H "Content-Type: application/json" \
    -d "{\"document_ids\": [$ID_LIST]}"
fi

检索与对话

直接检索（获取原文片段）

curl -X POST http://8.134.103.73:12700/api/v1/retrieval \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"question": "查询内容", "dataset_ids": ["2ccc31fe4f8511f181580bef240bdf9e"]}'

OpenAI 兼容对话（LLM 总结回答）

# 1. 创建 Chat Assistant
CHAT_ID=$(curl -s -X POST http://8.134.103.73:12700/api/v1/chats \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Assistant", "dataset_ids": ["2ccc31fe4f8511f181580bef240bdf9e"]}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['id'])")

# 2. 对话
curl -X POST "http://8.134.103.73:12700/api/v1/openai/$CHAT_ID/chat/completions" \
  -H "Authorization: Bearer ${RAGFLOW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"model\", \"messages\": [{\"role\": \"user\", \"content\": \"问题\"}], \"stream\": false}"

质量检查清单（每次上传后执行）

□ 文档格式符合标准（Markdown / 有标题层级）
□ 文件名遵循命名规范
□ 编码为 UTF-8
□ 上传成功（code=0）
□ 解析完成（run=DONE, status=1）
□ chunk_count > 0
□ 检索验证通过（返回相关结果，similarity > 0.3）
□ 无重复文档（上传前检查是否已存在同名文档）

错误处理

常见问题

文档解析后 chunk_count = 0

• 检查文件编码是否为 UTF-8
• 检查文件是否为空
• 检查解析配置中的 delimiter 是否匹配

检索相似度过低

• 知识库文档太少，补充更多相关文档
• 查询过于宽泛，换更具体的关键词
• 调整 similarity_threshold（当前 0.2）

辅助脚本

完整 CLI 工具: ragflow/opencaio.sh

bash ragflow/opencaio.sh status            # 知识库状态
bash ragflow/opencaio.sh upload file.md    # 上传文档
bash ragflow/opencaio.sh list              # 文档列表
bash ragflow/opencaio.sh search "query"    # 检索
bash ragflow/opencaio.sh chat "question"   # AI 对话

执行约束

1. 上传前必须通过内容质量检查
2. 上传后必须等待解析完成并验证
3. 批量上传必须间隔 ≥ 2 秒，避免触发限流
4. 不要上传包含敏感信息的文档
5. 重复文档先删除旧版再上传新版
6. 上传失败立即报告，附错误信息
7. 每次操作后更新 memory 记录变更