RAGFlow 入库说明

RAGFlow 的接入方式有很多种，但咱们今天要聊的这个场景稍微有点特殊——外部已经完成了解析和切片，RAGFlow 只要老老实实做好“入库工”就行。来看看 platform/ragflow_client/ragflow_ingestor 目录是怎么干的。

先说几个核心判断：这套流程的核心思路是，把 RAGFlow 当作一个“纯语义检索库”来用，那些传统的文档解析、切片、metadata 生成，全部在外部搞定。RAGFlow 在里面主要负责三件事：保存已经切好的 semantic chunks、对 chunk 内容做 embedding 和索引、以及在 UI 和 API 里完成检索和问答。反过来，解析原始 PDF、重新切片、生成 metadata 这些事情，RAGFlow 一概不管。

那在实际操作中，这套机制具体是怎么跑起来的？咱们从头捋一遍。

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

每个原始 AUTOSAR 规范文档，建议准备下面这些文件。

1.1 必须文件

output//chunks/.chunks.jsonl 是核心。这个文件里的每一行，代表一个已经切好的 chunk。

每个 chunk 通常长这样：

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

各个字段的用途，简单说：

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

1.2 建议文件

output//normalized/.normalized.md 是清洗后的 Markdown 原文，方便人工回溯。可以上传到 RAGFlow File Management，但不建议放进正式知识库。

1.3 可选文件

原始 PDF（template/.pdf）同样可以上传到 File Management，作为附件，不要进知识库。

2. RAGFlow 中保存哪些内容

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

2.1 Dataset / Knowledge Base

正式知识库只存 semantic chunks，来源就是那个 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 参与检索，metadata/PDF 进 File Management 只做附件，通过 file_id 下载。

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

这个问题值得单独拿出来说。metadata_sidecar.json 是结构化索引文件，不是规范原文证据。如果把它当成普通文档放进知识库，后果很麻烦：

• RAGFlow 会把 JSON 内容切片向量化。
• 检索结果可能全是 metadata JSON 片段，而不是 AUTOSAR 原文。
• UI 来源会显示 JSON，阅读体验极差。
• JSON 被切碎后，没法稳定按 LocalChunkID 做精确回查。
• 还会污染正式问答知识库。

所以最稳妥的做法是：metadata_sidecar.json 只上传到 File Management，不 link-to-datasets，然后把 file_id 写入 document meta_fields。

4. RAGFlow UI 来源显示规则

RAGFlow UI 问答后的检索来源，只会显示正式知识库中的 chunk content。换句话说，UI 里能看到的就是 Add chunk API 上传的 content，而 metadata_sidecar.json、normalized.md、原始 PDF 这些，只要没 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] ...

这样做，UI 里查看来源时，文件、模块、平台、chunk 类型、requirement ID、章节路径、原始文本证据，一目了然。

5. 核心入口函数

入库的入口函数是 ingest_chunks_to_ragflow，位于 platform/ragflow_client/ragflow_ingestor/pipeline.py。这个函数负责整个流程编排。

6. 入库过程说明

ingest_chunks_to_ragflow() 的完整流程，大致可以拆成以下几个阶段。

6.1 读取 chunks.jsonl

代码先读取 chunks_jsonl_path，转换成 ChunkRecord 对象列表。每个对象代表一个本地 semantic chunk。

6.2 校验 chunk

检查 local_chunk_id、chunk_order、chunk_type、content 是否存在，以及 chunk 顺序是否可排序。如果不通过，会记录到入库报告的 warnings。

6.3 source 一致性校验

检查文件名、document_name、source_markdown_file、chunk.metadata 等是否一致。如果开启了 strict_source_validation=True，发现明显不一致时会直接阻止入库。这套校验是为了避免用户以为自己上传的是 NetworkManagementInterface，实际 chunks 文件却是 NetworkManagement。

6.4 payload 质量检查

上传前检查每条 chunk 的内容质量，比如 content 里有没有 LocalChunkID、ChunkType，requirement chunk 有没有 RequirementID，important_keywords 和 tag_kwd 是否为空等。结果会写入入库报告中的 payload_quality。

6.5 解析或创建 dataset

有 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 参数控制：raise 直接报错，append 追加可能产生重复，replace 删除旧文档重建再上传。正式入库推荐使用 replace，避免重复 chunk。

6.8 初次写入 document meta_fields

把文档级 metadata 写入 RAGFlow document，比如标准族、平台、版本、模块、切片策略等。这些用于说明整个文档属于哪个平台、哪个模块、哪个版本。

6.9 构造 Add chunk payload

真正上传的字段是 content、important_keywords、tag_kwd。如果 pass_through_questions=True 且 chunk 里有 questions，会额外上传。但当前项目默认不生成 questions，所以通常保持 False。

6.10 content header 增强

如果开启 enable_payload_enrichment=True，代码会自动保证 chunk content 里有 LocalChunkID、SourceFile、Platform、Module、ChunkType、RequirementID 等关键 header。这些会参与文本检索，也会在 UI 来源中显示。

6.11 important_keywords 增强

从 chunk.metadata 中自动补齐 important_keywords，比如 SWS ID、RS ID、API name、error code 等。这能显著提升精确检索命中率。

6.12 tag_kwd 增强

自动补齐 tag_kwd，推荐标签包括 AUTOSAR、AP/CP、release、module、spec_type、chunk_type 等。这些用于稳定分类，不放长文本。

6.13 上传 chunk

逐条调用 RAGFlow Add chunk API。每条结果记录到 upload_results，包含 local_chunk_id、状态、ragflow_chunk_id 等。单条失败不会中断后续上传。

6.14 校验 RAGFlow chunk 数量

上传后调用 list chunks 接口，检查实际 chunk 数量是否一致。不一致会进 warnings。

6.15 生成 metadata_sidecar.json

上传完成后，生成 sidecar 文件，保存本地 chunk 与 RAGFlow chunk 的映射关系。后续 API 检索时，可以通过 LocalChunkID 回查完整 metadata。

6.16 上传支持文件到 File Management

如果启用相关参数，代码会把 metadata_sidecar.json、normalized.md、原始 PDF、ingest_report.json 上传到 RAGFlow File Management。注意，这些文件只存储，不 link-to-datasets，不会被解析、切片、embedding、检索。

6.17 二次更新 document meta_fields

支持文件上传成功后，把对应的 file_id 写入 document meta_fields，方便后续下载。

6.18 写入入库报告

最终生成 ragflow_ingest_report.json，包含 dataset_id、document_id、chunks 数量、校验结果、警告等所有信息。

7. dry_run 模式

设置 dry_run=True 时，不会真正调用 RAGFlow API（创建 dataset/document、上传 chunk/sidecar/PDF 等全都不做）。但仍然会读取 chunks.jsonl、校验 chunk、做 source 一致性检查、payload 质量检查，并生成 dry-run 版本的 metadata_sidecar.json 和入库报告。建议首次入库前，一定先跑一次 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 相关错误码有哪些？”之类的。UI 检索来源会显示 semantic chunk 的 content，所以里面应该能看到 LocalChunkID、SourceFile、Platform、Module、ChunkType、RequirementID、SectionPath 和原始文本证据。

11. 后续 API 检索使用方式

业务系统调用 RAGFlow API 后，建议按这个流程处理：RAGFlow 返回 chunk → 从 chunk.content 解析 LocalChunkID → 从 document_metadata 读取 sidecar_file_id → 通过 File Management 下载 metadata_sidecar.json → 用 LocalChunkID 查完整 metadata → 按 chunk_type / priority_for_generation 做二次排序 → 组装 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。如果放进去，会被 RAGFlow 自己切出另一套 chunks，和工程生成的混在一起，严重影响检索质量。

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

不会，前提是它只上传到 File Management，没有 link-to-datasets。UI 来源只显示 Dataset 里的 chunk content。

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

不会，同样前提是只放在 File Management，没进 Dataset。

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

不推荐上传为普通 dataset document。如果确实需要显示附件入口，可以创建一个 type=empty 的占位 document，把 file_id 写到 meta_fields，但不要给它添加 chunks。还是优先推荐用 File Management。

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

可以，但需保证 sidecar 已成功上传到 File Management，sidecar_file_id 已写入 document meta_fields，且入库报告里保存了 file_id。如果开启了 delete_local_sidecar_after_upload=True，上传成功后会自动删除本地文件。生产环境建议至少保留入库报告。

13. 推荐检查清单

入库前检查：

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

入库后检查：

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

14. 推荐知识库划分

AP 和 CP 强烈建议分开建知识库，比如 AUTOSAR_AP_SWS_R22_11 和 AUTOSAR_CP_SWS_R21_11。原因很简单：术语体系不同、API 风格不同、配置结构不同，分开后检索范围更可控，UI 问答时也不容易混淆。每个原始规范文档对应一个 RAGFlow document，不建议一个 chunk 一个 document。

15. 一句话总结

这个目录的职责就是标准而稳定地把外部切好的 xxx.chunks.jsonl 写入 RAGFlow empty document，让 semantic chunks 参与检索和 UI 来源展示；同时把 metadata 和原始文档作为 File Management 附件保存，通过 document meta_fields 建立关联，方便后续按 LocalChunkID 回查完整信息。