AUTOSAR AP 文档切分方法说明
AUTOSAR AP 文档语义切分：按代码执行顺序讲清楚
文档定位：本文按照
process_autosar_markdown()的代码执行顺序说明 AUTOSAR AP 文档切分链路，包括每一步先做什么、为什么做、怎么做、输出什么，以及如何检查结果是否合理。
0. 一句话介绍
platform/autosar_chunker 是一个面向 AUTOSAR 规范文档的本地语义切分引擎。它的核心不是固定长度切片，也不是让大模型判断语义，而是通过规则化解析把 AUTOSAR Markdown 文档转换成：
Markdown 原文
-> MarkdownBlock
-> SectionNode
-> AutoDocumentProfile
-> SemanticUnit
-> Chunk
-> chunks.jsonl / chunks_md / debug / report
最终目标是把 AUTOSAR AP SWS 从一篇长文档，转换成可追溯、可检索、可审计的语义证据集合，供后续 RAGFlow 入库、需求检索、测试用例生成和测试脚本生成使用。
当前切分入口明确不做这些事情：
不调用 LLM
不调用视觉模型
不调用 RAGFlow API
不做 embedding
不做 rerank
不写向量库
不生成 questions
因此，当前链路的特点是：离线、确定性、可复现、可调试、可审计。
1. 主入口
核心入口是：
from platform.autosar_chunker.pipeline import process_autosar_markdown
result = process_autosar_markdown(
input_md_path="template/AUTOSAR_SWS_Persistency.md",
output_dir="output",
profile_override={
"platform": "AP",
"spec_type": "SWS",
"module": "Persistency",
"release": "R22-11",
},
)
入口文件：
platform/autosar_chunker/pipeline.py
入口函数：
process_autosar_markdown()
这个函数是整个切分流程的编排器。它不把复杂逻辑全部写在入口里，而是按阶段调用不同模块：
parsing/
profile/
detectors/
strategies/
units/
binding/
builders/
writers/
validation/
工程说明口径：
该模块采用 pipeline 设计。入口只负责编排，不直接承载所有领域规则。解析、画像识别、block 增强、策略选择、语义单元构建、chunk 生成、输出校验分别拆到独立模块中，因此后续扩展 AP、CP、RS、TPS、ECUC 等不同文档策略时，不需要重写主流程。
2. 总执行顺序
process_autosar_markdown() 的真实执行顺序如下：
1. 解析输入路径、输出路径、合并 metadata/default/config
2. 创建 normalized/debug/chunks/chunks_md/reports 输出目录
3. load_markdown 读取 Markdown 原文
4. normalize_markdown 规范化 Markdown 文本
5. parse_markdown_blocks 解析为有序 MarkdownBlock
6. build_section_tree 构建章节树，并把 section_path 写回 block
7. detect_auto_profile 自动识别文档画像，并给 block/section 标注 doc_region
8. enrich_requirement_blocks 增强 requirement block
9. enrich_table_blocks 增强 table block
10. enrich_figure_blocks 增强 image/figure block
11. enrich_api_blocks 标记 API 候选 block
12. select_chunk_strategy 根据 profile 选择策略
13. strategy.build_units 构造 SemanticUnit
14. _blocks_from_semantic_units 恢复参与切分的 block 流
15. bind_contexts 绑定前后文、表格、图片、桥接上下文
16. build_chunks_from_units 把 SemanticUnit 转成最终 Chunk
17. write debug 文件
18. write_chunks_jsonl 输出 chunks.jsonl
19. write_markdown_chunks 输出逐片 Markdown
20. validate_output_consistency 校验输出一致性
21. write_ingest_report 输出质量报告
22. 返回 ChunkingResult
后续章节按这个顺序展开。
3. 第一阶段：解析入参并准备输出环境
入口首先把 input_md_path 和 output_dir 转为绝对路径，然后复制并合并三类配置：
DOCUMENT_METADATA
CHUNK_METADATA_DEFAULTS
CHUNKING_CONFIG
如果调用方传入 document_metadata、chunk_metadata_defaults、chunking_config 或 profile_override，则使用这些入参覆盖默认值。入口还会强制设置：
generate_questions = False
随后根据输入文件推导源文件 metadata：
source_file = <stem>.pdf
source_markdown_file = <input_md_path.name>
source_original_file = <stem>.pdf
例如：
输入：AUTOSAR_SWS_Persistency.md
source_file：AUTOSAR_SWS_Persistency.pdf
source_markdown_file：AUTOSAR_SWS_Persistency.md
source_original_file：AUTOSAR_SWS_Persistency.pdf
然后创建五类输出目录：
output/
normalized/
debug/
chunks/
chunks_md/
reports/
这五类目录分别用于保存规范化 Markdown、中间调试文件、最终 JSONL chunk、逐片 Markdown 和质量报告。
4. 第二阶段：读取并规范化 Markdown
入口调用：
markdown = load_markdown(source_path)
normalized = normalize_markdown(markdown)
load_markdown() 负责检查路径是否存在、是否是文件，并用 UTF-8 读取 Markdown 原文。
normalize_markdown() 负责做基础清洗：
统一换行符
调用 clean_autosar_text 清理 AUTOSAR 文本噪声
压缩过多连续空行
保留原文结尾换行语义
规范化结果会写入：
output/normalized/<doc_stem>.normalized.md
这个文件用于确认输入是否已经被正确读取和清洗。如果后续 block 解析异常，应先检查 normalized 文件。
5. 第三阶段：解析 MarkdownBlock
入口调用：
blocks = parse_markdown_blocks(normalized)
parse_markdown_blocks() 按原文顺序把 Markdown 切成有序 MarkdownBlock。
不是按固定字数切，也不是按 token 切，而是按 Markdown 结构语法 + AUTOSAR 特征规则 切
Markdown 本身是一种轻量标记语言，常见结构包括 heading、paragraph、list、code block、image 等
代码里定义了这些正则：
HEADING_RE = r"^(?P<marks>#{1,6})\s+(?P<title>.+?)\s*$"
IMAGE_RE = r"!\[.*?\]\((?P<url>.*?)\)"
FIGURE_CAPTION_RE = ...
HTML_TABLE_START_RE = r"<table\b"
HTML_TABLE_END_RE = r"</table>"
CODE_FENCE_RE = r"^\s*```"
REQUIREMENT_START_RE = r"^\s*\[(?:SWS|RS|SRS|TPS|EXP|ECUC)_..."
拆分流程如下：
先把 Markdown 按行拆开，
然后用 index 从上到下顺序扫描，
按 heading / code block / HTML table / Markdown table / image / figure caption / list / paragraph 的优先级识别结构块，
每识别一个块就立即 append 到 blocks，
并按 append 顺序生成 block_id 和 global_order，
同时记录原始 line_start / line_end。
切分依据是：
Markdown 显式结构标记
+ HTML table 标记
+ AUTOSAR requirement ID 起始模式
+ Figure caption 模式
+ list 模式
+ paragraph 边界规则
每个 block 包含：
block_id
global_order
type
text
line_start
line_end
metadata
支持识别的基础类型包括：
heading
paragraph
requirement
table
image
figure_caption
list
code_block
解析顺序是：
heading
code_block
HTML table
Markdown table
image
figure_caption
list
paragraph
关键规则：
只有 paragraph 可以升级为 requirement。
这样可以避免 Requirements Tracing 表、API 参数表、目录或变更历史中出现的 [SWS_xxx] 被误判为规范性需求。
6. 第四阶段：构建章节树 SectionNode
入口调用：
sections, section_warnings = build_section_tree(blocks)
章节树构建的目的是给每个 block 绑定完整章节信息：
section_number
section_title
section_path
section_level
parent_sections
top_level_chapter
例如：
7 Functional Specification
> 7.2 Persistency
> 7.2.1 Initialization and Shutdown
会变成：
section_path = "7 Functional Specification > 7.2 Persistency > 7.2.1 Initialization and Shutdown"
章节树还会识别 Contents/TOC，并标记：
enabled_for_ingest = False
disabled_reason = contents
这样目录内容不会进入后续高价值语义切分。
具体来看，章节信息会进入后面切分出的每个chunk，整体流程是，
先写回 MarkdownBlock，再随 SemanticUnit 进入 Chunk.metadata，最后又通过 content prefix 写入 Chunk.content。这就是章节树信息进入最终 chunk 的完整路径
7. 第五阶段：识别 AutoDocumentProfile 和 doc_region
入口调用：
profile = detect_auto_profile(
input_path=source_path,
markdown_text=normalized,
blocks=blocks,
sections=sections,
profile_override=profile_override,
)
这一步识别文档画像，包括：
| 字段 | 说明 |
|---|---|
platform | AP、CP 或 UNKNOWN |
spec_type | SWS、RS、TPS、EXP、ECUC 或 UNKNOWN |
release | 例如 R22-11 |
module | 例如 Persistency、CANStateManager |
api_style | AP 通常是 adaptive_cpp_api |
config_style | 配置风格 |
requirement_prefixes | 例如 SWS_PER、SWS_CanSM |
detected_namespaces | 例如 ara::core、ara::com |
detected_api_names | API 名称 |
detected_error_codes | 错误码 |
doc_regions | section_path 到区域的映射 |
warnings | 画像识别告警 |
同时，它会把每个 section 和 block 标注为不同 doc_region：
front_matter
contents
change_history
glossary
requirements_tracing
functional_specification
api_specification
service_interfaces
appendix_manifest_elements
appendix_normative_api
appendix_history
unknown
doc_region 是防误判的关键字段。同样出现 requirement ID，在第 6 章可能是追溯关系，在第 7 章可能是规范性需求，在目录或变更历史中则通常不应入库。
8. 第六阶段：Block 增强 enrich
入口按顺序执行：
enrich_requirement_blocks(blocks)
enrich_table_blocks(blocks)
enrich_figure_blocks(blocks, config)
enrich_api_blocks(blocks)
8.1 Requirement 增强
识别并补充：
requirement_id
requirement_status
requirement_family
requirement_text
该增强仍然只处理 paragraph，不处理 table。
8.2 Table 增强
给表格补充：
table_id
table_row_count
traceability_ids
referenced_requirement_ids
related_rs_ids
table_type
retrieval_usage
priority_for_generation
主要 table_type 包括：
requirements_tracing
front_matter
change_history
glossary
manifest_model_element
model_element_table
service_interface
api_parameter
api_error
config_parameter
error_mapping
generic_table
8.3 Figure 增强
图片处理模式是：
image_understanding_mode = caption_only
仅根据 caption、正文引用、同 section 附近描述性文本和图片路径判断是否入库。
没有 caption、没有正文引用、没有有效上下文的图片会被标记为：
chunk_type = image_noise
enabled_for_ingest = False
8.4 API 候选增强
如果 paragraph 或 table 中出现多个 API 字段标签，例如：
Kind
Symbol
Scope
Syntax
Parameters
Return value
Errors
Header file
Description
则标记：
api_candidate = True
这只是候选标记，真正的 AP C++ API unit 会在策略阶段按 section 聚合生成。
9. 第七阶段：选择切分策略
入口调用：
strategy = select_chunk_strategy(profile)
策略选择规则：
ECUC -> AutosarEcucStrategy
AP + SWS -> AutosarApSwsStrategy
CP + SWS -> AutosarCpSwsStrategy
RS -> AutosarRsStrategy
TPS -> AutosarTpsStrategy
其他 -> AutosarGenericStrategy
对于 AP SWS 文档，需要满足：
profile.platform == "AP"
profile.spec_type == "SWS"
然后选择：
autosar_ap_sws
10. 第八阶段：构造 SemanticUnit
入口调用：
semantic_units = strategy.build_units(
blocks=blocks,
sections=sections,
profile=profile,
config=config,
)
对于 AP SWS，策略按顺序构造：
1. requirement
2. requirement_group
3. traceability
4. adaptive_cpp_api
5. service_interface
6. error_code
7. config_parameter
8. model_element
9. figure
10. table
11. section_explanation
12. sort_and_deduplicate
引入 SemanticUnit 的原因是：MarkdownBlock 只是原文结构单元，不一定等于业务语义单元。例如一个 API 说明可能跨多个 paragraph、code_block 和 table；一个 Service Interface 可能由连续多张表组成；一个 traceability 关系可能来自大表中的多行。
10.1 Requirement Unit
正式 requirement 满足：
block.type == requirement
且 doc_region 不在 blocked regions
blocked regions 包括：
requirements_tracing
contents
front_matter
disclaimer
change_history
appendix_not_applicable_requirements
设计原则：
一条规范性 requirement = 一个 requirement SemanticUnit = 一个 requirement chunk
主要 metadata：
primary_requirement_id
requirement_ids
section_path
section_context
lead_context
post_context
bridge_context
sibling_requirement_ids
previous_requirement_id
next_requirement_id
explicit_related_requirement_ids
retrieval_usage = fallback_requirement_lookup
evidence_role = normative_requirement
priority_for_generation = P0
10.2 Traceability Unit
只处理 requirements tracing 表：
block.type == table
且 doc_region == requirements_tracing
或 table_type == requirements_tracing
默认按父需求聚合：
RS_xxx_00001 -> [SWS_xxx_00010, SWS_xxx_00011]
最终生成：
chunk_type = traceability
priority_for_generation = P2
10.3 Adaptive C++ API Unit
按 API section 聚合：
paragraph
code_block
table
list
并提取：
api_name
api_full_name
namespace
class_name
method_name
return_type
related_requirement_ids
AP C++ API 识别信号包括：
ara::xxx
ara::core::Result<T>
Class::Method
class Xxx
10.4 Service Interface Unit
默认启用：
group_service_interface_tables_by_requirement = True
同一 section、同一 requirement 下的连续 service interface 表会被聚合成一个 unit。
提取字段包括：
service_interface_name
service_interface_namespace
service_interface_kind
service_interface_fields
service_interface_attributes
service_interface_symbols
related_requirement_ids
symbol_normalization_warnings
10.5 Error Code Unit
只允许从以下区域生成：
functional_specification
api_specification
service_interfaces
错误行为上下文包括：
shall return the error
return the error
error code
ErrorCode
ErrorDomain
Exception
ara::core::Result
ara::core::ErrorCode
Return value
这样可以避免目录、变更历史、普通枚举符号污染 error_code 证据。
10.6 Config Parameter / Model Element Unit
配置关键词包括：
Manifest
Deployment
Machine Manifest
Execution Manifest
Service Instance Manifest
PortPrototypeToDeploymentMapping
模型关键词包括：
Functional Cluster
Adaptive Application
Process
Machine
Service Interface
命中后生成 config_parameter 或 model_element。其中 model_element 最终会映射为 section_background。
10.7 Table / Figure / Section Background Unit
普通表格会按行数和字符数拆分，并保留表头。Figure 只基于 caption 和上下文生成。普通章节说明会映射为 section_background，作为低优先级背景证据。
11. 第九阶段：绑定上下文
入口先从 SemanticUnit 中恢复参与切分的 block 流：
unit_blocks = _blocks_from_semantic_units(semantic_units)
然后调用：
contexts = bind_contexts(unit_blocks, config)
BoundContext 包含：
section_intro
lead_context
post_context
bridge_context
related_tables
related_figures
nearby_context_before
nearby_context_after
caption_block
绑定逻辑分三类：
_bind_requirement_contexts
_bind_table_contexts
_bind_figure_contexts
这样做的目的不是把整节内容塞进 chunk，而是给 requirement、table 和 figure 补充有限、可控的局部上下文。
12. 第十阶段：SemanticUnit 转 Chunk
入口调用：
chunks = build_chunks_from_units(
semantic_units,
contexts,
stem,
doc_meta,
defaults,
config,
)
最终 Chunk 包含：
local_chunk_id
chunk_order
chunk_type
content
important_keywords
tag_kwd
metadata
global_order_start
global_order_end
previous_chunk_id
next_chunk_id
unit_type 到 chunk_type 的核心映射：
| unit_type | chunk_type |
|---|---|
requirement | requirement |
traceability_row_group | traceability |
api | api |
service_interface | service_interface |
error_code | error_code |
config_parameter | config_parameter |
model_element | section_background |
section_explanation | section_background |
figure | figure |
table | table |
glossary | glossary |
requirement_group | 不输出 |
image_noise | 不输出 |
典型优先级：
| chunk_type | evidence_role | priority |
|---|---|---|
requirement | normative_requirement | P0 |
api | api_specification | P1 |
error_code | error_behavior | P1 |
service_interface | service_interface | P1 |
table | table_evidence | P1 |
config_parameter | configuration_parameter | P2 |
section_background | section_background | P2 |
figure | figure_context | P2 |
traceability | requirements_traceability | P2 |
所有 chunks 会按：
global_order_start
global_order_end
排序，然后重新编号：
chunk_order = 1, 2, 3, ...
并补充：
previous_chunk_id
next_chunk_id
因此最终 JSONL 的顺序与原文语义顺序一致。
13. 第十一阶段：写出结果文件
如果 export_debug=True，输出：
output/debug/<doc_stem>.auto_profile.json
output/debug/<doc_stem>.semantic_units.json
output/debug/<doc_stem>.blocks.json
output/debug/<doc_stem>.section_tree.json
然后写出：
output/chunks/<doc_stem>.chunks.jsonl
output/chunks_md/*.md
chunks.jsonl 按 chunk_order 写入，一行一个 JSON chunk。chunks_md 会先删除旧 .md 文件，再按 chunk 顺序写出新的逐片 Markdown，便于人工检查内容。
14. 第十二阶段：输出一致性校验和质量报告
所有 writer 完成后，入口调用：
validate_output_consistency(...)
主要检查：
chunks.jsonl 是否存在且非空
chunks.jsonl 行数是否等于 expected_total_chunks
chunks_md 文件数是否等于 expected_total_chunks
blocks.json 是否非空
section_tree.json 是否非空
auto_profile.json 是否非空
semantic_units.json 是否非空
随后调用：
write_ingest_report(...)
输出：
output/reports/<doc_stem>.ingest_report.json
重点检查字段：
| 字段 | 意义 |
|---|---|
output_consistency.matched | 输出文件是否一致 |
requirements_detected | 检测到的正式 requirement 数 |
requirements_chunked | 生成的 requirement chunk 数 |
requirements_missing_chunk_ids | 检测到但没切出来的需求 |
requirements_without_context | 缺少上下文的需求数 |
tables_misclassified_as_requirement | 表格误判成需求的数量，期望为 0 |
traceability_tables_detected | 追溯表检测数量 |
api_sections_detected | API 章节检测数量 |
api_chunks_generated | API chunk 数量 |
figures_filtered_as_noise | 被过滤的图片数量 |
questions_generated | 固定为 0 |
15. 返回结果 ChunkingResult
入口最后返回 ChunkingResult，包含：
input_md_path
output_dir
normalized_md_path
blocks_json_path
section_tree_json_path
auto_profile_json_path
semantic_units_json_path
chunks_jsonl_path
chunks_md_dir
report_json_path
total_blocks
total_semantic_units
total_chunks
total_requirements
total_figures
total_tables
profile
warnings
调用方可以直接使用：
chunking_result.chunks_jsonl_path
chunking_result.normalized_md_path
chunking_result.report_json_path
chunking_result.profile
后续入库逻辑不需要重复手写路径，从而减少跨模块参数不一致。
16. 完整说明口径
该模块实现的是 AUTOSAR AP SWS 文档的本地语义切分。入口是 process_autosar_markdown。它先合并文档 metadata、chunk 默认字段和切分配置，然后创建 normalized、debug、chunks、chunks_md、reports 五类输出目录。
第一步读取 Markdown，并做换行和 AUTOSAR 文本清洗，生成 normalized.md，保证后续解析基于稳定输入。
第二步解析 MarkdownBlock。parser 按行识别 heading、paragraph、table、image、figure_caption、list、code_block。最关键的规则是只有 paragraph 可以升级成 requirement，表格和标题即使包含 SWS ID，也不会误判成需求。
第三步构建 section tree。它根据 AUTOSAR 章节编号重建完整 section_path，并把 section_path、section_number、section_title 写回每个 block。这样后面能知道内容属于 requirements tracing、functional specification、API specification 还是 appendix。
第四步自动识别 AutoDocumentProfile，判断文档是 AP 还是 CP，是 SWS、RS、TPS 还是 ECUC，同时识别 release、module、api_style、namespace、错误码、配置术语，并给 block 标注 doc_region。
第五步做 block enrich。Requirement enrich 补需求 ID 和状态；table enrich 判断 requirements_tracing、service_interface、api_error、manifest 等表格类型；figure enrich 基于 caption 和引用过滤图片噪声；api enrich 标记 API 候选块。
第六步根据 profile 选择策略。AP + SWS 会选择 autosar_ap_sws。这个策略会依次构建 requirement、traceability、adaptive C++ API、service_interface、error_code、config_parameter、model_element、figure、table、section_background 等 SemanticUnit。
第七步做上下文绑定。系统会给 requirement 绑定 section intro、lead context、post context、bridge context，也会给 table 和 figure 绑定附近上下文，避免 chunk 成为孤立片段。
第八步把 SemanticUnit 转成最终 Chunk。ChunkBuilder 会根据 unit_type 映射 chunk_type，生成不同 content 模板，补齐 retrieval_usage、evidence_role、priority_for_generation，再按原文 global_order 排序并设置 chunk_order、previous_chunk_id、next_chunk_id。
最后写出 debug 文件、chunks.jsonl、逐片 Markdown，并在全部落盘后做 output consistency 校验，再生成 ingest_report。整个流程不依赖 LLM 和 RAGFlow，适合离线批处理，结果可复现、可审计。
17. 简要说明口径
这个模块是 AUTOSAR AP SWS 的语义切分器。它不是按固定长度切，也不靠大模型切，而是先把 Markdown 解析成 block，再根据章节编号构建 section tree，自动识别 AP/SWS 文档画像和 doc_region。之后通过 AP SWS 策略把内容组织成 requirement、API、Service Interface、Error Code、Traceability、Table、Figure 等 SemanticUnit，最后转换成带 metadata 的 Chunk。Requirement 保持一条一个 chunk，API 和错误码作为补充证据，traceability 单独保留父子需求关系。最后输出 chunks.jsonl、chunks_md、debug 文件和 ingest_report，用报告检查表格误判、需求漏切、输出一致性和 API 覆盖情况。
18. 技术问答
Q1：为什么不按固定长度切？
固定长度会破坏 AUTOSAR 的语义边界：
一条 requirement 可能被切断
多个 requirement 可能被合并
API 参数表可能丢表头
Requirements Tracing 表可能被当成正文
Service Interface 表可能丢失接口含义
当前方法先识别结构和语义，再输出 chunk，更适合需求追溯和 RAG 检索。
Q2：为什么 requirement 一条一个 chunk？
因为测试设计和需求覆盖通常以 requirement ID 为最小追溯单元。如果多个 requirement 合并，会导致：
测试点归属不清
覆盖率统计不准确
模型生成时混淆不同需求
人工 review 难定位
所以当前策略是：
requirement 原子化 + metadata 记录关系 + 短上下文补充
Q3：如何避免表格误判成 requirement？
两层控制：
1. block parser 阶段只有 paragraph 允许升级为 requirement
2. table_detector 阶段表格里的 requirement ID 只作为 traceability/reference metadata
因此 Requirements Tracing 表不会变成 P0 requirement chunk。
Q4：AP SWS 和普通文档切分最大的不同是什么？
AP SWS 里除了需求，还有大量强结构化证据：
ara:: C++ API
Service Interface 表
ErrorDomain / ErrorCode / ara::core::Result
Manifest / Deployment / Machine / Process
Requirements Tracing 表
所以 AP SWS 策略必须单独处理 API、服务接口、错误码、配置和追溯关系，而不是只切段落。
Q5：为什么要有 doc_region？
同样的文本在不同区域语义不同。
例如：
第 6 章出现 SWS ID -> 追溯关系
第 7 章出现 SWS ID -> 功能需求
第 8 章出现 Errors -> API 错误行为
Change History 出现 Error -> 历史说明，不是错误码证据
Contents 出现章节标题 -> 目录，不入库
doc_region 是防误判的关键字段。
Q6：为什么不让 LLM 直接切？
因为切分边界必须稳定、可复现、可审计。LLM 适合做语义增强，但不适合覆盖：
requirement_id
section_path
doc_region
table_type
chunk_order
traceability relation
后续如果接 LLM，应该放在：
SemanticUnit 之后、Chunk 之前
只做测试意图总结、前置条件提取、期望行为总结等增强，并写入：
metadata.llm_enhancement
不能覆盖规则字段。
Q7：现在对markdown文档的切片里面有overlap吗？
当前 Markdown 切片没有传统 sliding-window overlap；
但部分语义 chunk 会主动复制相邻上下文，形成少量语义级 overlap。
| 类型 | 是否有传统 overlap | 是否有上下文复制 |
|---|---|---|
requirement | 否 | 有，section_intro / lead / post / bridge |
api | 否 | 基本无固定邻接 overlap，主要是 API 表格自身重复到多个标题区 |
error_code | 否 | 无固定 overlap |
config_parameter | 否 | 可能带 section context |
section_background | 否 | 否 |
table | 否 | 有 lead/post context；表格拆分时可能重复表头 |
figure | 否 | 有 before/after context |
| 超长 chunk 拆分 | 否 | 只保留 metadata prefix，不复制正文 overlap |
Q8：metadata的作用
content 负责“让模型读懂这段话”；metadata 负责“让系统知道这段话是什么、从哪来、和谁有关、该怎么用”
定位类 metadata：告诉我它从哪来
语义类 metadata：告诉我它是什么
控制类 metadata：告诉我后续怎么用它
important_keywords 和 tag_kwd 会参与检索增强，但不是关系链接。
官方说明 important_keywords 是 chunk 的 key terms / phrases，tag_kwd 是和 chunk 关联的 tag keywords。
有助于关键词召回，但它们不会让 RAGFlow 自动理解。
SWS_PduR_00654 -> 对应 API 表
API 表 -> 对应 header file
error_code -> 对应 requirement
这些“链接关系”还是要自己的 retrieval 模块处理
| 问题 | 答案 |
|---|---|
| RAGFlow 会不会自动读取你 sidecar 里的 metadata 做检索？ | 不会 |
RAGFlow 会不会自动根据 related_requirement_ids 做跳转？ | 不会 |
| RAGFlow 会不会自动把 API chunk 和 requirement chunk 关联起来？ | 不会 |
| RAGFlow 能不能用 metadata 过滤？ | 可以，但要显式传 metadata_condition |
| Add chunk 能不能直接传任意 chunk metadata？ | v0.25.6 官方 Add chunk 字段里没有任意 metadata |
| metadata 写进 content 前缀有没有用？ | 有，会参与文本检索和 LLM 上下文 |
important_keywords / tag_kwd 有没有用？ | 有，适合放需求 ID、API 名、错误码 |
| 真正的 AUTOSAR 关系链接应该在哪做？ | 在你自己的 ragflow_retrieval 后处理层做 |
19. 新文档处理检查清单
处理一个新的 AP SWS 文档时，按这个顺序检查：
1. normalized/*.normalized.md 是否结构正常
2. debug/*.blocks.json 中 block 类型是否合理
3. debug/*.section_tree.json 中 section_path 是否完整
4. debug/*.auto_profile.json 中 platform 是否为 AP
5. debug/*.auto_profile.json 中 spec_type 是否为 SWS
6. debug/*.auto_profile.json 中 api_style 是否为 adaptive_cpp_api
7. debug/*.semantic_units.json 中 requirement 是否一条一个 unit
8. debug/*.semantic_units.json 中 traceability 是否按父需求聚合
9. debug/*.semantic_units.json 中 API / service_interface / error_code 是否符合预期
10. chunks/*.chunks.jsonl 是否非空
11. chunks/*.chunks.jsonl 行数是否等于 total_chunks
12. chunks_md/*.md 数量是否等于 total_chunks
13. reports/*.ingest_report.json 中 output_consistency.matched 是否为 true
14. reports/*.ingest_report.json 中 tables_misclassified_as_requirement 是否为 0
15. reports/*.ingest_report.json 中 requirements_missing_chunk_ids 是否为空或可解释
16. reports/*.ingest_report.json 中 api_chunks_generated 是否符合文档实际情况
17. 确认 questions_generated 固定为 0
20. 总结
这套 AP 文档切分链路的本质是：
把 AUTOSAR AP SWS 长文档，转换成按原文顺序排列、带完整 metadata、可追溯、可检索、可审计的语义 chunk 集合。
核心价值：
1. 入口 pipeline 清晰，阶段职责明确
2. 不依赖 LLM，结果稳定可复现
3. requirement 保持原子化，适合需求追溯
4. AP C++ API、Service Interface、Error Code、Manifest 单独建模
5. traceability 表保留父子需求关系
6. table 和 figure 有噪声控制
7. chunks.jsonl 顺序与原文顺序一致
8. report 能做质量审计和问题定位
可以将该模块概括为：
该模块不是简单文本切片，而是把 AUTOSAR AP 规范里的需求、接口、错误码、服务接口、配置和追溯关系抽象成结构化证据，再用统一 Chunk schema 输出给 RAG 系统。这样后续做需求问答、测试用例生成或脚本生成时，模型拿到的是可追溯的工程证据，而不是一堆无边界的长文本。
脑启社区是一个专注类脑智能领域的开发者社区。欢迎加入社区，共建类脑智能生态。社区为开发者提供了丰富的开源类脑工具软件、类脑算法模型及数据集、类脑知识库、类脑技术培训课程以及类脑应用案例等资源。
更多推荐
7
0- 0
已为社区贡献4条内容
所有评论(0)