RAGFlow入库指南：配置与数据导入详解
RAGFlow 支持多种数据接入方式，但这里要解决的场景略有不同——外部系统已完成文档解析与切片，RAGFlow 只需专注执行“语义入库”职责。下面拆解 platform/ragflow_client/ragflow_ingestor 目录的具体实现。
先明确几个关键设计原则：这套方案的核心思路是把 RAGFlow 当作一个纯粹的语义检索库来使用。传统的文档解析、语义分块、标签与元数据生成全部在外部完成。RAGFlow 内部只负责三件事：存储已切好的语义块（semantic chunks）、对 chunk 文本做向量化与索引构建、在 UI 及 API 层面提供检索与问答能力。反过来，解析原始 PDF、重新进行语义分块、生成元数据等任务 RAGFlow 一概不参与。
实际运行时，这套机制如何串联？从零开始梳理完整流程。
1. 入库前需要准备哪些文件
每个 AUTOSAR 规范文档，建议按以下文件清单准备。
1.1 必须文件
output/ 是核心文件。该文件中每一行代表一个已经语义分块完毕的 chunk。
典型 chunk 结构如下：
{"local_chunk_id": "...","chunk_order": 1,"chunk_type": "requirement","content": "...","important_keywords": [],"tag_kwd": [],"metadata": {}}
各字段作用说明：
| 字段 | 作用 |
|---|---|
local_chunk_id | 本地主键，用于关联 sidecar 元数据。 |
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 级元数据，仅在本地保留，不上传至 RAGFlow。 |
1.2 建议文件
output/ 是清洗后的 Markdown 原文，便于人工回溯校验。该文件可以上传至 RAGFlow File Management，但不建议加入正式知识库。
1.3 可选文件
原始 PDF（template/）也可上传至 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，就不会出现在 UI 来源中。
因此 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 类型、需求 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，不会被解析、切片、嵌入、检索。
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 | 文档级元数据。 | 建议传入 |
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。若将 PDF 或 Markdown 放入，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 回查完整信息。