跳到主要内容

RAGFlow 技术方案

# RAGFlow 技术方案

1. 覆盖范围​

RAGFlow 是 LLM-WIKI MVP 的智能体与 RAG 平台，负责支撑文档迭代、知识问答、引用生成和反馈闭环。

LLM-WIKI 产品RAGFlow 支撑能力产品特性
文档迭代智能体Agent、知识库、工具调用、任务工作流文档整理、补全、重组、改进建议
知识索引产品文档解析、chunk、检索、重排RAG 召回和引用定位
问答产品Chat/API、引用回答、无答案处理面向人和智能体的问答能力
反馈与任务产品问答结果、引用、低置信反馈生成文档改进任务
权限与身份产品RAGFlow API token、工作区权限智能体调用边界
配置管理产品数据集、模型、检索策略配置可审计的问答策略

2. 如何购买或获取​

2.1 MVP 决策​

当前已经部署 RAGFlow，因此 MVP 直接复用现有 RAGFlow 环境。

RAGFlow 的获取方式分两类：

方式适用场景MVP 建议
已部署自建 RAGFlow已有服务器、数据和网络环境采用
RAGFlow Cloud/托管形态希望减少运维暂不作为 MVP 前提

2.2 成本边界​

MVP 成本主要来自：

  • 已部署 RAGFlow 的服务器资源。
  • RAGFlow 调用的模型 API。
  • 文档解析、embedding、问答生成产生的 token 或推理成本。
  • Meilisearch 作为独立站内全文搜索服务会产生额外成本。
  • 向量存储不作为独立 MVP 产品单列，按 RAGFlow 实施依赖处理；当前倾向优先评估 pgvector。

3. 如何开发​

3.1 LLM-WIKI 与 RAGFlow 的边界​

RAGFlow 负责“智能处理知识”，LLM-WIKI 负责“治理知识生产”。

边界RAGFlowLLM-WIKI
文档读取读取已审批或待迭代文档决定哪些文档可被读取
文档解析chunk、embedding、召回提供页面路径、来源、版本、质量状态
文档改写生成建议或内容草稿把结果转成 Git diff 和 PR
问答生成带引用答案统一 Answer API、权限、反馈任务
发布不负责正式发布只发布已审批 publish/**

3.2 必须开发的 RAGFlow Adapter​

MVP 需要在 LLM-WIKI 中开发 RagflowAdapter。

职责：

  • 同步 publish/** 中允许进入知识库的文档到 RAGFlow dataset。
  • 调用 RAGFlow 问答 API。
  • 调用 RAGFlow Agent 或工作流执行文档迭代任务。
  • 将 RAGFlow 输出转换为 LLM-WIKI 标准结果。
  • 记录 RAGFlow 请求、响应、引用和失败原因。

建议接口：

class RagflowAdapter:
    def upsert_documents(self, docs: list[DocumentRecord]) -> IndexResult: ...
    def delete_documents(self, document_ids: list[str]) -> IndexResult: ...
    def ask(self, question: QuestionRequest) -> AnswerResult: ...
    def run_iteration(self, task: IterationTask) -> IterationResult: ...

3.3 标准输入输出​

问答输入​

{
  "question": "kunora-kgent 如何配置 agent memory?",
  "scope": {
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "main"
  },
  "require_citations": true,
  "caller": "human"
}

问答输出​

{
  "answer": "...",
  "citations": [
    {
      "path": "publish/system/components/kunora-kgent/...md",
      "title": "...",
      "anchor": "...",
      "chunk_id": "..."
    }
  ],
  "confidence": "medium",
  "no_answer_reason": null,
  "improvement_task": null
}

文档迭代输出​

RAGFlow 只输出结构化建议或内容草稿，不输出 Git 分支、commit 或 PR 信息。Git 产物由 AgentBridge 根据该输出生成。

{
  "summary": "补充 agent memory 配置说明",
  "changes": [
    {
      "path": "publish/system/components/kunora-kgent/...md",
      "action": "update",
      "reason": "现有说明缺少参数含义",
      "evidence": [
        {
          "path": "publish/system/components/kunora-kgent/...md",
          "anchor": "..."
        }
      ],
      "draft_content": "..."
    }
  ],
  "risk": "低风险，仅补充说明",
  "requires_human_review": true
}

4. 如何部署​

4.1 已部署 RAGFlow 的接入要求​

需要确认以下信息：

配置项说明
RAGFLOW_BASE_URLRAGFlow API 地址
RAGFLOW_API_KEYLLM-WIKI 调用 RAGFlow 的 API token
RAGFLOW_DATASET_IDLLM-WIKI 文档知识库 dataset
RAGFLOW_AGENT_ID文档迭代 Agent 或 workflow 标识
RAGFLOW_QA_APP_ID问答应用标识，如 RAGFlow 区分应用
RAGFLOW_TIMEOUT_SECONDS请求超时

这些值不写入仓库明文，放入 GitHub Actions Secrets 或运行环境变量。

4.2 网络要求​

调用方向要求
GitHub Actions -> RAGFlowActions runner 能访问 RAGFlow API
LLM-WIKI Answer API -> RAGFlow运行时服务能访问 RAGFlow API
RAGFlow -> 模型服务RAGFlow 能访问所选商业 LLM API

如果 RAGFlow 部署在内网，GitHub-hosted runner 可能无法访问，需要自托管 runner 或中间 API 网关。

5. 如何配置​

5.1 LLM-WIKI 配置​

config/ragflow.yaml 建议结构：

ragflow:
  baseUrlEnv: RAGFLOW_BASE_URL
  apiKeyEnv: RAGFLOW_API_KEY
  datasetIdEnv: RAGFLOW_DATASET_ID
  agentIdEnv: RAGFLOW_AGENT_ID
  qaAppIdEnv: RAGFLOW_QA_APP_ID
  indexing:
    includeStatuses:
      - approved
    excludePatterns:
      - "**/draft/**"
    chunkMetadata:
      - sourceProject
      - sourceRef
      - pagePath
      - headingAnchor
      - qualityStatus
  qa:
    requireCitations: true
    noAnswerCreatesIssue: true
    maxRetrievedChunks: 8
  iteration:
    outputMode: pull-request
    allowDirectPublish: false

5.2 RAGFlow 数据集配置​

RAGFlow 是 MVP 的 RAG 索引事实入口。LLM-WIKI 不在 MVP 中维护第二套独立向量索引，避免 chunk、embedding、引用和删除同步不一致。

如果 RAGFlow 底层需要选择向量存储，优先评估 pgvector，因为它可以复用 PostgreSQL 运维体系，减少独立向量数据库的部署、备份和权限治理成本。若 RAGFlow 当前部署已经固定使用其他向量/检索组件，则先按现状接入，不把该组件暴露为 LLM-WIKI MVP 的独立产品边界。

5.3 RAGFlow 数据集划分​

RAGFlow 中建议至少建立两个 dataset：

Dataset用途
llm-wiki-approved已审批正式文档，用于用户问答
llm-wiki-working发布工作目录或待迭代文档，用于智能体整理

这样可以避免未审批内容进入正式问答。

5.4 RAGFlow 数据集生命周期​

两个 dataset 的隔离必须落实为同步生命周期，而不是只停留在命名约定。

Dataset更新触发输入范围删除策略失败状态
llm-wiki-workingSync PR 合并、人工触发迭代、冲突处理任务publish/** 工作目录中允许迭代的文档以工作目录 manifest 为准删除缺失文档阻塞对应迭代任务，不影响正式问答
llm-wiki-approvedRelease PR 合并到 main 且发布校验通过已审批、可发布、qaVisible=true 的文档以发布 manifest 为准删除缺失文档标记索引失败，正式问答继续使用上一版可用索引

约束：

  • 正式问答只能访问 llm-wiki-approved。
  • 文档迭代可以访问 llm-wiki-working，但输出仍必须回到 Release PR。
  • 每次 upsert/delete 后都要更新 state/index-manifest.json。
  • 删除必须显式同步到 RAGFlow，不能只追加新文档。
  • 索引失败不能把未审批或半更新内容暴露给用户。

5.5 向量存储实施倾向​

MVP 不单列向量数据库产品。向量存储属于 RAGFlow 的内部实施选择。

优先倾向：pgvector。

理由：

  • 复用 PostgreSQL，减少一套独立向量数据库运维。
  • 备份、权限、监控和网络治理可以沿用已有数据库体系。
  • MVP 阶段数据规模可控，pgvector 足够支撑早期 RAG 验证。
  • 后续如果问答规模、召回性能或向量检索能力不足，再通过 ADR 评估专用向量数据库。

约束：

  • LLM-WIKI 不直接操作 pgvector 表。
  • LLM-WIKI 只通过 RAGFlow API 同步文档和发起问答。
  • pgvector schema、embedding 表和检索策略由 RAGFlow 实施方案管理。

5.5.1 pgvector 评估附录​

pgvector 只作为 RAGFlow 底层向量存储候选，不作为 LLM-WIKI 独立技术产品。

评估前提：

  • 现有 RAGFlow 部署支持或可以迁移到 pgvector。
  • 团队已有 PostgreSQL 运维能力。
  • MVP 文档规模和问答并发不需要专用向量数据库能力。

评估项：

项目验证方式
RAGFlow 兼容性确认当前 RAGFlow 版本是否支持 pgvector 或对应存储配置
索引性能用 llm-wiki-approved 样本文档测试 embedding 写入和召回延迟
删除一致性删除 publish 页面后确认 RAGFlow 不再召回旧 chunk
备份恢复验证 PostgreSQL 备份恢复后 RAGFlow dataset 可用
权限隔离RAGFlow 使用独立数据库账号，不复用管理员账号

不做事项：

  • LLM-WIKI 不创建或迁移 pgvector schema。
  • LLM-WIKI 不直接写 embedding 表。
  • LLM-WIKI 不绕过 RAGFlow 查询 pgvector。

决策规则：

  • 如果现有 RAGFlow 已稳定使用其他向量存储，MVP 先沿用现状。
  • 如果新建或迁移成本低，优先评估 pgvector。
  • 如果数据规模、召回性能或多租户隔离要求超过 pgvector 能力，再通过 ADR 评估专用向量数据库。

5.6 RAGFlow Agent 配置​

文档迭代 Agent 必须遵守：

  • 只能建议修改 publish/**。
  • 必须输出修改理由。
  • 必须保留或生成引用依据。
  • 不能输出“已发布”结论。
  • 不能绕过 GitHub PR。

6. 如何使用​

6.1 文档索引​

触发时机：

  • Release PR 合并到 main 后。
  • 人工手动重建索引。
  • RAGFlow dataset 配置变化后。

流程：

  1. LLM-WIKI 扫描 publish/**。
  2. 生成 DocumentRecord，包含路径、标题、内容、来源、版本、质量状态。
  3. 调用 RagflowAdapter.upsert_documents。
  4. 记录索引 manifest。

6.2 用户问答​

流程：

  1. 用户在文档站页面或 API 提问。
  2. LLM-WIKI Answer API 添加 scope、权限和引用要求。
  3. 调用 RAGFlow 问答能力。
  4. 将 RAGFlow 结果标准化为 AnswerResult。
  5. 前端展示答案、引用和反馈按钮。

6.3 智能体文档迭代​

流程：

  1. GitHub Issue、人工命令或同步冲突触发迭代任务。
  2. LLM-WIKI 创建 IterationTask。
  3. RAGFlow Agent 读取相关文档和上下文。
  4. RAGFlow 输出改进建议或内容草稿。
  5. LLM-WIKI 把结果写入分支并创建 Release PR。
  6. 人工审批后合并。

7. 错误处理​

错误处理
RAGFlow 不可达workflow 失败，保留日志，不修改发布目录
无引用答案返回 no-answer，不展示编造答案
Agent 输出非结构化标记任务失败，要求重试或人工处理
文档索引失败阻塞发布后的索引状态，但不回滚已审批文档
RAGFlow 返回低置信结果展示低置信提示，并提供反馈入口

8. 安全要求​

  • RAGFLOW_API_KEY 不进入 Git。
  • RAGFlow 不能直接写 GitHub main，也不能直接创建最终发布结果。
  • 正式问答只使用 llm-wiki-approved dataset。
  • 工作区 dataset 不对普通用户开放。
  • 所有 Agent 输出必须先由 AgentBridge 校验结构、引用和目标路径，再进入 PR 审批。

9. 验收标准​

验收项标准
接入LLM-WIKI 能成功调用已部署 RAGFlow API。
索引已审批文档能进入 RAGFlow dataset。
问答问答返回结构化答案和引用。
无答案无证据时不编造答案，并能创建改进任务。
迭代RAGFlow Agent 能生成文档修改建议，AgentBridge 能把建议转换成 Git diff 并创建 Release PR。
隔离未审批文档不进入正式问答 dataset；working 和 approved 的 upsert/delete 生命周期可审计。

10. 官方资料​

编辑此页
◇对此页面有疑问？

问答功能将在后续接入 Answer API。当前可通过页面底部的反馈链接提交问题。

页面来源草稿
来源项目kunora-wiki
分支docs-publish
路径technology/components/kunora-wiki/product/07-mvp-technical-solution/04-ragflow.md