RAGFlow入库操作指南

作者：技术拾光时间：2026-06-09 06:30:07浏览：250

RAGFlow 的接入方式有多种，但本文讨论的场景较为特殊：外部已完成解析和切片，RAGFlow 仅需执行“入库”操作。以下解析 platform/ragflow_client/ragflow_ingestor 目录的实现方式。核心思路明确：将 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。若放入 PDF 或 Markdown，RAGFlow 会自行切分另一套 chunks，与工程生成的 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 回查完整信息。