RAGFlow 入库说明

dyw_mail

409人浏览 · 2026-06-07 09:50:02

dyw_mail · 2026-06-07 09:50:02 发布

本文档说明 platform/ragflow_client/ragflow_ingestor 目录内的代码如何把外部切片结果上传到 RAGFlow，并说明推荐的使用方式。

当前工程的入库方式是：

外部文档解析和切片
  ↓
xxx.chunks.jsonl
  ↓
RAGFlow empty document
  ↓
Add chunk API
  ↓
RAGFlow embedding / indexing / retrieval

也就是说，RAGFlow 在这里主要负责：

1. 保存已经切好的 semantic chunks。
2. 对 chunk 内容进行 embedding 和索引。
3. 在 UI 页面和 API 中完成检索、问答和来源展示。

RAGFlow 不负责：

1. 解析原始 PDF。
2. 解析 Markdown 原文档。
3. 重新切片。
4. 生成 chunk metadata。
5. 保存任意 chunk-level metadata。

1. 入库前需要准备哪些文件

每个原始 AUTOSAR 规范文档建议准备以下文件。

1.1 必须文件

output/<module>/chunks/<document>.chunks.jsonl

这是实际进入 RAGFlow 知识库的核心文件。文件中每一行对应一个已经切好的 chunk。

每个 chunk 通常包含：

{
  "local_chunk_id": "...",
  "chunk_order": 1,
  "chunk_type": "requirement",
  "content": "...",
  "important_keywords": [],
  "tag_kwd": [],
  "metadata": {}
}

其中：

字段	作用
`local_chunk_id`	本地 chunk 主键，用于后续和 sidecar metadata 关联。
`chunk_order`	chunk 顺序。
`chunk_type`	chunk 类型，例如 `requirement`、`api`、`traceability`、`config_parameter`。
`content`	上传到 RAGFlow 的正文，也是 UI 检索来源中显示的主要内容。
`important_keywords`	强检索词，例如 SWS ID、RS ID、API 名、错误码、配置项。
`tag_kwd`	分类标签，例如 AUTOSAR、AP、CP、模块名、chunk 类型。
`metadata`	完整 chunk 级 metadata，本地保留，不直接作为 RAGFlow metadata 字段上传。

1.2 建议文件

output/<module>/normalized/<document>.normalized.md

用于保存清洗后的 Markdown 原文，便于人工回溯。该文件可以上传到 RAGFlow File Management，但不建议进入正式知识库参与解析、切片、embedding 和检索。

1.3 可选文件

template/<document>.pdf

如果需要保留原始 PDF，可以上传到 RAGFlow File Management 作为附件文件。它不应进入正式知识库参与解析、切片、embedding 和检索。

2. RAGFlow 中保存哪些内容

本工程把 RAGFlow 分成两类用途。

2.1 Dataset / Knowledge Base

正式知识库中只保存 semantic chunks。

RAGFlow Dataset
  └── RAGFlow document
        ├── chunk 1
        ├── chunk 2
        └── chunk N

这些 chunk 来自：

xxx.chunks.jsonl

RAGFlow UI 问答后的检索来源显示的就是这些 chunk 的 content。

2.2 File Management

File Management 只作为文件存储使用，可以保存：

metadata_sidecar.json
normalized.md
原始 PDF
ingest_report.json

这些文件不应该调用 link-to-datasets，也不应该进入正式知识库参与检索。

推荐关系：

semantic chunks
  -> Dataset / Knowledge Base
  -> 参与检索和 UI 来源展示

metadata_sidecar.json / normalized.md / PDF
  -> File Management
  -> 只作为附件存储
  -> 通过 file_id 下载

3. 为什么不能把 metadata_sidecar.json 当普通文档入库

metadata_sidecar.json 是结构化索引文件，不是规范原文证据。

如果把它作为普通文档加入知识库并解析，会出现以下问题：

1. RAGFlow 会把 JSON 内容切片和向量化。
2. 检索结果可能返回大量 metadata JSON，而不是 AUTOSAR 原文。
3. UI 来源会显示 JSON 片段，影响阅读。
4. JSON 被切碎后，无法稳定按 LocalChunkID 做精确回查。
5. 会污染正式问答知识库。

因此推荐做法是：

metadata_sidecar.json
  -> 上传到 RAGFlow File Management
  -> 不 link-to-datasets
  -> file_id 写入 document meta_fields

4. RAGFlow UI 来源显示规则

RAGFlow UI 问答后的检索来源只会显示正式知识库中的 chunk 内容。

也就是说，UI 来源显示的是：

Add chunk API 上传的 content

不会显示：

1. metadata_sidecar.json
2. normalized.md
3. 原始 PDF

前提是这些文件只上传到 File Management，没有 link 到 dataset。

因此，chunk 的 content 必须写得足够清晰。建议内容格式如下：

# LocalChunkID: AUTOSAR_SWS_PDURouter__requirement__SWS_PduR_00216
# SourceFile: AUTOSAR_SWS_PDURouter.md
# SourceMarkdown: AUTOSAR_SWS_PDURouter.md
# SourceOriginal: AUTOSAR_SWS_PDURouter.pdf
# StandardFamily: AUTOSAR
# Platform: CP
# Release: R21-11
# Module: PDURouter
# SpecType: SWS
# ChunkType: requirement
# RetrievalUsage: fallback_requirement_lookup
# EvidenceRole: normative_requirement
# PriorityForGeneration: P0
# RequirementID: SWS_PduR_00216
# SectionPath: 7 Functional specification > ...
# DocRegion: functional_specification

## Original Text
[SWS_PduR_00216] ...

这样在 RAGFlow UI 中查看来源时，可以直接看到：

1. 来源文件。
2. 模块。
3. 平台。
4. chunk 类型。
5. requirement ID。
6. 章节路径。
7. 原始文本证据。

5. 核心入口函数

入库主入口是：

from platform.ragflow_client import ingest_chunks_to_ragflow

核心实现在：

platform/ragflow_client/ragflow_ingestor/pipeline.py

函数：

ingest_chunks_to_ragflow(...)

该函数负责完整流程编排。

6. 入库过程说明

ingest_chunks_to_ragflow() 的主要流程如下。

6.1 读取 chunks.jsonl

代码会先读取：

chunks_jsonl_path

并转换为 ChunkRecord 对象列表。

每个 ChunkRecord 表示一条本地 semantic chunk。

6.2 校验 chunk

代码会检查：

1. local_chunk_id 是否存在。
2. chunk_order 是否存在。
3. chunk_type 是否存在。
4. content 是否存在。
5. chunk 顺序是否可排序。

如果存在问题，会进入入库报告的 warnings。

6.3 source 一致性校验

代码会检查以下内容是否一致：

1. chunks_jsonl_path 文件名。
2. document_name。
3. document_meta_fields.source_markdown_file。
4. chunk.metadata.source_markdown_file。
5. normalized_md_path。
6. original_pdf_path。

如果 strict_source_validation=True，发现明显不一致时会直接阻止入库。

这个校验用于避免以下问题：

用户以为上传 NetworkManagementInterface，实际 chunks 文件却是 NetworkManagement。

6.4 payload 质量检查

代码会在上传前检查每条 chunk 的入库 payload 质量，例如：

1. content 中是否有 LocalChunkID。
2. content 中是否有 ChunkType。
3. requirement chunk 是否有 RequirementID。
4. important_keywords 是否为空。
5. tag_kwd 是否为空。
6. tag_kwd 是否包含 chunk_type。

检查结果会写入入库报告中的：

payload_quality

6.5 解析或创建 dataset

如果传入 dataset_id，优先使用 dataset_id。

如果只传入 dataset_name，代码会查找同名知识库。

如果知识库不存在且：

create_dataset_if_missing=True

则会自动创建知识库。

6.6 解析或创建 document

每个原始规范文档对应 RAGFlow 一个 document。

代码会根据 document_name 查找文档。

如果文档不存在且：

create_document_if_missing=True

则会创建一个 empty document。

empty document 的作用是承载外部已经切好的 semantic chunks。

6.7 处理已有 document

参数：

if_document_exists="replace"

可选值：

参数值	行为
`raise`	如果文档已存在，直接报错。
`append`	追加 chunk，可能造成重复。
`replace`	删除旧文档，重新创建 empty document，再上传全部 chunk。

建议正式入库使用：

if_document_exists="replace"

这样可以避免重复 chunk。

6.8 初次写入 document meta_fields

代码会把文档级 metadata 写入 RAGFlow document。

示例：

{
  "standard_family": "AUTOSAR",
  "platform": "CP",
  "release": "R21-11",
  "module": "PDURouter",
  "spec_type": "SWS",
  "source_markdown_file": "AUTOSAR_SWS_PDURouter.md",
  "source_original_file": "AUTOSAR_SWS_PDURouter.pdf",
  "chunking_strategy": "external_autosar_semantic_chunk_v1",
  "ingest_mode": "empty_document_add_chunk",
  "parser": "platform.autosar_chunker",
  "ragflow_parse": false
}

这些是 document 级 metadata，用于说明整个文档属于哪个平台、哪个模块、哪个版本。

6.9 构造 Add chunk payload

真正上传到 RAGFlow 的字段包括：

{
  "content": "...",
  "important_keywords": [],
  "tag_kwd": []
}

如果：

pass_through_questions=True

并且 chunk 中存在 questions，则会额外上传：

{
  "questions": []
}

当前项目默认不生成 questions，因此一般保持：

pass_through_questions=False

6.10 content header 增强

如果启用：

enable_payload_enrichment=True

代码会自动确保 chunk content 中包含关键 header，例如：

LocalChunkID
SourceFile
Platform
Module
ChunkType
RequirementID
SectionPath
DocRegion
APIName
ErrorCode

这些 header 会参与 RAGFlow 的文本检索，也会在 UI 来源中显示。

6.11 important_keywords 增强

代码会从 chunk.metadata 中自动补齐 important_keywords。

例如：

SWS ID
RS ID
SRS ID
ECUC ID
API name
callback name
scheduled function name
error code
return code
service interface name
configuration parameter
container name
module
release
platform
chunk type

这些词有助于提升精确检索命中率。

6.12 tag_kwd 增强

代码会自动补齐 tag_kwd。

推荐标签包括：

AUTOSAR
AP / CP
release
module
spec_type
chunk_type
doc_region
retrieval_usage
evidence_role
priority_for_generation

tag_kwd 用于稳定分类，不放长文本。

6.13 上传 chunk

代码会逐条调用 RAGFlow Add chunk API。

每条上传结果会记录到：

upload_results

其中包含：

local_chunk_id
chunk_order
status
ragflow_chunk_id
error_message

单条 chunk 上传失败不会中断后续 chunk。

6.14 校验 RAGFlow chunk 数量

上传后，代码会调用 RAGFlow list chunks 接口，检查 RAGFlow 中实际 chunk 数量。

结果写入：

verification_chunk_count

如果成功上传数和 RAGFlow 返回数量不一致，会进入 warnings。

6.15 生成 metadata_sidecar.json

chunk 上传完成后，代码会生成：

metadata_sidecar.json

它保存本地 chunk 与 RAGFlow chunk 的映射关系。

结构示例：

{
  "AUTOSAR_SWS_PDURouter__requirement__SWS_PduR_00216": {
    "local_chunk_id": "AUTOSAR_SWS_PDURouter__requirement__SWS_PduR_00216",
    "ragflow_chunk_id": "...",
    "dataset_id": "...",
    "dataset_name": "AUTOSAR_CP_SWS_R21_11",
    "document_id": "...",
    "document_name": "AUTOSAR_SWS_PDURouter",
    "chunk_order": 1,
    "chunk_type": "requirement",
    "important_keywords": [],
    "tag_kwd": [],
    "metadata": {},
    "upload_status": "success",
    "error_message": null
  }
}

后续 API 检索时，可以通过：

LocalChunkID

回查完整 chunk metadata。

6.16 上传支持文件到 File Management

如果启用相关参数，代码会把以下文件上传到 RAGFlow File Management：

metadata_sidecar.json
normalized.md
原始 PDF
ingest_report.json

注意：这些文件只上传到 File Management，不会 link-to-datasets。

因此它们不会：

1. 被解析。
2. 被切片。
3. 被 embedding。
4. 参与检索。
5. 出现在 UI 检索来源中。

6.17 二次更新 document meta_fields

支持文件上传成功后，代码会把对应 file_id 写入 document meta_fields。

示例：

{
  "sidecar_file_id": "...",
  "sidecar_file_name": "AUTOSAR_SWS_PDURouter.metadata_sidecar.json",
  "sidecar_file_size": 123456,
  "normalized_md_file_id": "...",
  "normalized_md_file_name": "AUTOSAR_SWS_PDURouter.normalized.md",
  "original_pdf_file_id": "...",
  "original_pdf_file_name": "AUTOSAR_SWS_PDURouter.pdf",
  "support_files_uploaded": true,
  "support_files_storage": "ragflow_file_management"
}

后续 API 检索时，可以从 document metadata 中拿到 sidecar_file_id，再下载 sidecar 文件。

6.18 写入入库报告

最终会生成：

ragflow_ingest_report.json

报告中包含：

dataset_id
document_id
chunks_jsonl_path
metadata_sidecar_path
sidecar_file_id
normalized_md_file_id
original_pdf_file_id
total_chunks
success_chunks
failed_chunks
verification_chunk_count
payload_quality
source_validation
upload_results
support_file_upload_results
warnings

7. dry_run 模式

如果设置：

dry_run=True

则不会真实调用 RAGFlow API。

不会执行：

1. 创建 dataset。
2. 创建 document。
3. 上传 chunk。
4. 上传 sidecar。
5. 上传 normalized.md。
6. 上传 PDF。
7. 更新 document meta_fields。

但仍会：

1. 读取 chunks.jsonl。
2. 校验 chunk。
3. 做 source 一致性检查。
4. 做 payload 质量检查。
5. 生成 dry-run 版本的 metadata_sidecar.json。
6. 生成入库报告。

建议首次入库前先执行 dry_run。

8. 推荐使用方式

8.1 CP 文档入库示例

from platform.ragflow_client import ingest_chunks_to_ragflow

result = ingest_chunks_to_ragflow(
    chunks_jsonl_path="output/pdur/chunks/AUTOSAR_SWS_PDURouter.chunks.jsonl",
    ragflow_base_url="http://10.0.17.56:9380",
    api_key="YOUR_RAGFLOW_API_KEY",

    dataset_name="AUTOSAR_CP_SWS_R21_11",
    document_name="AUTOSAR_SWS_PDURouter",
    document_meta_fields={
        "standard_family": "AUTOSAR",
        "platform": "CP",
        "release": "R21-11",
        "module": "PDURouter",
        "spec_type": "SWS",
        "source_markdown_file": "AUTOSAR_SWS_PDURouter.md",
        "source_original_file": "AUTOSAR_SWS_PDURouter.pdf",
        "chunking_strategy": "external_autosar_semantic_chunk_v1",
        "ingest_mode": "empty_document_add_chunk",
        "parser": "platform.autosar_chunker",
        "ragflow_parse": False,
    },

    output_report_path="output/pdur/reports/AUTOSAR_SWS_PDURouter.ragflow_ingest_report.json",

    metadata_sidecar_path="output/pdur/reports/AUTOSAR_SWS_PDURouter.metadata_sidecar.json",
    upload_sidecar_to_ragflow_files=True,

    normalized_md_path="output/pdur/normalized/AUTOSAR_SWS_PDURouter.normalized.md",
    upload_normalized_md_to_ragflow_files=True,

    original_pdf_path="template/AUTOSAR_SWS_PDURouter.pdf",
    upload_original_pdf_to_ragflow_files=False,

    create_document_if_missing=True,
    create_dataset_if_missing=True,
    if_document_exists="replace",
    update_document_metadata=True,

    dry_run=False,
    timeout=120,
    max_retries=3,
    retry_sleep_seconds=2,
    pass_through_questions=False,

    strict_source_validation=True,
    enable_payload_enrichment=True,
    write_metadata_sidecar_file=True,
)

8.2 AP 文档入库示例

from platform.ragflow_client import ingest_chunks_to_ragflow

result = ingest_chunks_to_ragflow(
    chunks_jsonl_path="output/per/chunks/AUTOSAR_SWS_Persistency.chunks.jsonl",
    ragflow_base_url="http://10.0.17.56:9380",
    api_key="YOUR_RAGFLOW_API_KEY",

    dataset_name="AUTOSAR_AP_SWS_R22_11",
    document_name="AUTOSAR_SWS_Persistency",
    document_meta_fields={
        "standard_family": "AUTOSAR",
        "platform": "AP",
        "release": "R22-11",
        "module": "Persistency",
        "spec_type": "SWS",
        "source_markdown_file": "AUTOSAR_SWS_Persistency.md",
        "source_original_file": "AUTOSAR_SWS_Persistency.pdf",
        "chunking_strategy": "external_autosar_semantic_chunk_v1",
        "ingest_mode": "empty_document_add_chunk",
        "parser": "platform.autosar_chunker",
        "ragflow_parse": False,
    },

    output_report_path="output/per/reports/AUTOSAR_SWS_Persistency.ragflow_ingest_report.json",

    metadata_sidecar_path="output/per/reports/AUTOSAR_SWS_Persistency.metadata_sidecar.json",
    upload_sidecar_to_ragflow_files=True,

    normalized_md_path="output/per/normalized/AUTOSAR_SWS_Persistency.normalized.md",
    upload_normalized_md_to_ragflow_files=True,

    create_document_if_missing=True,
    create_dataset_if_missing=True,
    if_document_exists="replace",
    update_document_metadata=True,

    dry_run=False,
    strict_source_validation=True,
    enable_payload_enrichment=True,
    write_metadata_sidecar_file=True,
)

9. 参数说明

参数	含义	推荐值
`chunks_jsonl_path`	上游切片结果路径。	必填
`ragflow_base_url`	RAGFlow 服务地址。	必填
`api_key`	RAGFlow API Key。	必填
`dataset_name`	知识库名称。	推荐传入
`dataset_id`	知识库 ID。优先级高于 `dataset_name`。	可选
`document_name`	RAGFlow document 名称。	每个规范文档一个 document
`document_meta_fields`	文档级 metadata。	推荐传入
`output_report_path`	入库报告路径。	推荐传入
`metadata_sidecar_path`	sidecar 输出路径。	推荐传入
`upload_sidecar_to_ragflow_files`	是否上传 sidecar 到 File Management。	`True`
`normalized_md_path`	normalized Markdown 路径。	可选
`upload_normalized_md_to_ragflow_files`	是否上传 normalized Markdown 到 File Management。	按需
`original_pdf_path`	原 PDF 路径。	可选
`upload_original_pdf_to_ragflow_files`	是否上传原 PDF 到 File Management。	按需
`create_document_if_missing`	文档不存在时是否创建。	`True`
`create_dataset_if_missing`	知识库不存在时是否创建。	测试环境可为 `True`
`if_document_exists`	文档存在时如何处理。	`replace`
`update_document_metadata`	是否更新 document meta_fields。	`True`
`dry_run`	是否只生成计划，不真实入库。	首次建议先 `True`
`strict_source_validation`	source 不一致时是否阻断。	`True`
`enable_payload_enrichment`	是否增强 content / keywords / tags。	`True`
`write_metadata_sidecar_file`	是否生成 sidecar。	`True`

10. 后续 RAGFlow UI 使用方式

入库完成后，可以在 RAGFlow UI 中直接提问，例如：

SWS_PduR_00216 是什么要求？
PduR_Transmit 相关错误码有哪些？
CanSM BusOff 后有哪些状态迁移？
SWS_PER_00408 相关 API 和错误码是什么？
NetworkStateType 有哪些状态值？

UI 检索来源显示的是 semantic chunk 的 content。

因此来源中应该能看到：

1. LocalChunkID。
2. SourceFile。
3. Platform / Module / Release。
4. ChunkType。
5. RequirementID / APIName / ErrorCode。
6. SectionPath。
7. Original Text 原文证据。

11. 后续 API 检索使用方式

后续业务系统调用 RAGFlow API 后，建议按以下流程处理：

RAGFlow retrieval / chat API 返回 chunk
  ↓
从 chunk.content 解析 LocalChunkID
  ↓
从 document_metadata 中读取 sidecar_file_id
  ↓
通过 RAGFlow File Management 下载 metadata_sidecar.json
  ↓
用 LocalChunkID 查完整 metadata
  ↓
按 chunk_type / priority_for_generation / requirement_id 做二次排序
  ↓
组装 LLM 上下文

推荐上下文优先级：

优先级	chunk 类型
P0	`requirement`
P1	`api`、`service_interface`、`error_code`、`return_code`、`callback`、`scheduled_function`
P2	`traceability`、`config_parameter`、`ecuc_container`、`sequence_diagram`、`figure`、`glossary`、`section_background`
P3	`not_applicable_reference`、`appendix_history`、`low_priority_metadata`

12. 常见问题

12.1 是否需要把 PDF 或 Markdown 上传到正式知识库？

不建议。

正式知识库只应该包含 semantic chunks。

如果把 PDF 或 Markdown 上传到正式知识库并解析，会产生另一套 RAGFlow 自己切出来的 chunks，和工程生成的 semantic chunks 混在一起，影响检索质量。

12.2 metadata_sidecar.json 是否会在 UI 来源里显示？

不会。

前提是它只上传到 RAGFlow File Management，没有 link-to-datasets。

UI 来源只显示进入 Dataset 的 chunk content。

12.3 normalized.md 和 PDF 是否会在 UI 来源里显示？

不会。

前提是它们只上传到 RAGFlow File Management，没有进入 Dataset。

12.4 能否让 sidecar / markdown / pdf 显示在知识库文档列表，但不参与检索？

不推荐上传为普通 dataset document。

如果确实需要在知识库中显示一个附件入口，可以创建一个 type=empty 的附件占位 document，并把 file_id 写到它的 meta_fields。不要给该占位 document 添加 chunks，也不要上传文件让 RAGFlow 解析。

推荐优先使用 File Management，而不是占位 document。

12.5 是否可以上传后删除本地 metadata_sidecar.json？

可以，但需要保证：

1. sidecar 已成功上传到 RAGFlow File Management。
2. sidecar_file_id 已写入 document meta_fields。
3. 入库报告中保存了 sidecar_file_id。

如果设置：

delete_local_sidecar_after_upload=True

则上传成功后会删除本地 sidecar 文件。

生产环境中建议至少保留入库报告，便于排查。

13. 推荐检查清单

入库前检查：

1. chunks.jsonl 是最新切片结果。
2. report 中 requirements_detected == requirements_chunked。
3. report 中 normative_blocks_not_referenced = 0。
4. chunks_jsonl_path、document_name、source_markdown_file 一致。
5. dry_run=True 能通过。

入库后检查：

1. success_chunks 等于 total_chunks。
2. failed_chunks = 0。
3. verification_chunk_count 与 success_chunks 基本一致。
4. sidecar_file_id 已写入 document meta_fields。
5. RAGFlow UI 按 SWS ID 可以召回对应 requirement chunk。
6. RAGFlow UI 来源中能看到 Original Text。
7. API 返回 chunk.content 后可以解析 LocalChunkID。
8. LocalChunkID 可以在 sidecar 中找到完整 metadata。

14. 推荐知识库划分

建议 AP 和 CP 分开建知识库：

AUTOSAR_AP_SWS_R22_11
AUTOSAR_CP_SWS_R21_11

原因：

1. AP 和 CP 的术语体系不同。
2. API 风格不同。
3. 配置结构不同。
4. 检索时更容易控制范围。
5. UI 问答时不容易混淆。

每个原始规范文档对应一个 RAGFlow document。

不建议一个 chunk 一个 document。

15. 一句话总结

platform/ragflow_client/ragflow_ingestor 的职责是：

把外部已经切好的 xxx.chunks.jsonl 稳定写入 RAGFlow empty document，
让 semantic chunks 参与检索和 UI 来源展示，
同时把 metadata_sidecar.json / normalized.md / PDF 作为 File Management 附件保存，
并通过 document meta_fields 建立 file_id 关联，
方便后续 API 检索后按 LocalChunkID 回查完整 metadata。

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

图解 AI Agent：Agent = 模型 + Harness

—指围绕"模型该看到什么"做的系统性设计，是 Harness 工程里最核心的一块，Fowler 那篇文章的原文观点是：上下文工程就是把 guides 和 sensors 交付到 Agent 面前的手段[1]。它标准化的是 Harness 里"工具层"的接口，是 Harness 的一个零件，不是 Harness 本身。Claude Code、Codex、开源的 opencode，内核都是这个循环的工