RAGFlow OpenCAIO 知识库管理 Skill

RAGFlow OpenCAIO 知识库管理

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

配置信息

| 配置项 | 值 | |--------|-----| | 服务器地址 | http://8.134.103.73:12700 | | API Key | ragflow-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo | | 知识库 ID | 2ccc31fe4f8511f181580bef240bdf9e | | 知识库名称 | OpenCAIO | | 嵌入模型 | text-embedding-v2@Tongyi-Qianwen | | 对话模型 | deepseek-v4-flash@DeepSeek | | 分块方法 | naive (512 tokens/chunk) | | GraphRAG | 开启 | | RAPTOR | 开启 | | 语言 | English |

API 端点速查

| 操作 | 方法 | 端点 | |------|------|------| | 知识库状态 | GET | /api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e | | 上传文档 | POST | /api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/documents | | 文档列表 | GET | /api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/documents | | 删除文档 | DELETE | /api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/documents | | 解析文档 | POST | /api/v1/datasets/2ccc31fe4f8511f181580bef240bdf9e/chunks | | 添加分块 | POST | /api/v1/datasets/{id}/documents/{doc_id}/chunks | | 检索知识 | POST | /api/v1/retrieval | | OpenAI 对话 | POST | /api/v1/openai/{chat_id}/chat/completions | | 创建对话 | POST | /api/v1/chats |

通用请求头

Authorization: Bearer ragflow-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo
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

分类检查清单

上传前必须确认：

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

文档上传标准（强制）

1. 文档格式要求

| 标准 | 要求 | 说明 | |------|------|------| | 文件格式 | .md 优先，支持 .txt .pdf .docx .html | Markdown 结构清晰，解析效果最好 | | 文件名 | {类别}_{主题}_{日期}.md | 例: product_opencaio-intro_2026-05-19.md | | 编码 | UTF-8 | 避免中文乱码 | | 大小 | 单文件 ≤ 10MB | 超大文件拆分上传 |

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. 文档命名规范

| 类别 | 路径格式 | 示例 | |------|------|------| | 技能定义 | skills/{skill-name}/ | skills/ragflow-opencaio/SKILL.md | | Agent配置 | agents/{agent-name}/ | agents/protocols/A2A-Protocol_v1.md | | 公司资料 | company/ | company/OpenCAIO产品介绍_2026-05-19.md | | 规范规则 | standards/ | standards/taxonomy-rules_v1.1.md | | 记忆归档 | memories/ | memories/architecture-decision_2026-05-19.md |

标准工作流

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-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo" \
  -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-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo" \
  -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-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo" \
  | 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-mlZjyQxsDT27bhT6tbONrn0f6dyA-g6hR1jcRqh1lNo" \
  -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 $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 $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 $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 $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 $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）
□ 无重复文档（上传前检查是否已存在同名文档）

错误处理

| 错误码 | 含义 | 处理 | |--------|------|------| | 401 | API Key 无效 | 检查 API Key 是否正确 | | 102 | 知识库为空/无分块 | 上传并解析文档 | | 102 | content is required | 手动添加分块时缺少 content 字段 | | 102 | document_ids is required | 解析/删除时缺少 document_ids | | 400 | 文件格式不支持 | 转换为 .md/.txt/.pdf 格式 |

常见问题

文档解析后 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 对话

执行约束

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

Agent Skills: RAGFlow OpenCAIO 知识库管理

Install this agent skill to your local

Skill Files