测试 Markdown 文档【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora这是一个测试 Markdown 文档用于测试 Markdown 解析功能。包含图片测试图片包含链接这是一个测试链接。包含代码块def hello_world(): print(Hello, World!)包含表格表头1表头2内容1内容2内容3内容4测试分块功能这部分内容用于测试分块功能确保 Markdown 结构在分块时保持完整。第一块内容第二块内容第三块内容测试重叠功能这部分内容可能会在分块时与前后块重叠以确保上下文的连续性。这份文件虽然短小却是一份经过精心设计的语法全覆盖夹具它依次验证了解析链路中的每个关键能力 | 语法要素 | 测试意图 | 对应的解析/分块机制 | |---|---|---| | #/## 标题层级 | 标题结构识别 | HeaderTracker 表头追踪与上下文保留 | | 测试图片 | 图片语法提取 | MarkdownImageUtil.extract_image / extract_base64 | | 测试链接 | 链接语法保护 | protected_regex 中的 \[.*?\]\(.*?\) | | 围栏代码块 python | 代码块整体保留 | protected_regex 中的代码块规则 | | GFM 表格 | 表格标准化与列对齐 | MarkdownTableUtil.format_table | | 分块功能段落 | 结构完整性 | TextSplitter._split / _merge | | 重叠功能段落 | 相邻块上下文连续性 | chunk_overlap 重叠机制 | 在 [docreader/testdata](https://link.gitcode.com/i/3f719c3334c2ed8816093eae46f02dab) 目录下与 test.md 并排的还有 test.html、test.txt、test_download.txt 以及 images/ 测试图片目录共同构成 docreader 多格式解析的测试素材集。其中 test.md 专责 Markdown 路线。 ### test.md 的三种真实用途 从仓库使用点看这份夹具至少在三处被直接引用 1. **本地解析调试脚本的示例输入**[docreader/scripts/parse_local.py](https://link.gitcode.com/i/f2f289036c18ab2ef8060f7f86397eab) 的文档字符串将 docreader/testdata/test.md 作为第一个示例命令PYTHONPATH. docreader/.venv/bin/python docreader/scripts/parse_local.py docreader/testdata/test.md2. **gRPC 端到端测试的测试文件**[docreader/client/client_test.go](https://link.gitcode.com/i/47c277a87611630d59713c39307f2b02) 的 TestReadFile 通过 os.ReadFile(../testdata/test.md) 读取该文件构造 ReadRequest{FileContent, FileName: test.md, FileType: md} 发给 DocReader 服务并断言返回的 MarkdownContent 非空见 [client_test.go](https://link.gitcode.com/i/47c277a87611630d59713c39307f2b02#L63-L95)。 3. **Markdown 表格格式化的行为基准**test.md 中的 GFM 表格与 [docreader/tests/test_markdown_table_util.py](https://link.gitcode.com/i/586bccaa611a0868e8c9460345377124) 中 test_format_nonempty_table 等用例验证的是同一套格式化逻辑。 也就是说无论你通过 gRPC 服务、Go 客户端还是 Python 直接调用test.md 都是验证Markdown 能否被正确解析的最短路径。 ## Markdown 解析流水线从注册到两阶段处理 ### 解析器注册md/markdown 指向 MarkdownParser docreader 通过引擎注册表管理文件类型 → 解析器类的映射。[docreader/parser/registry.py](https://link.gitcode.com/i/a6ff9bbccfc348b56fb832f1ff50a6d3) 的 _build_default_registry() 在内置引擎builtin中注册了 python md: MarkdownParser, markdown: MarkdownParser,即扩展名为.md或.markdown的文件默认由MarkdownParser处理。除此之外注册表还内置了markitdown微软 MarkItDown 库与opendataloaderPDF 版面分析两个引擎当请求引擎不支持某类型时会依次回退到类型级默认引擎如 ppt/pptx/csv 回退 markitdown再回退 builtin见 registry.py。文件类型并非只信扩展名docreader/parser/parser.py 中的detect_effective_file_type会检查文件魔数——若扩展名为.docx但内容以 OLE 复合文档魔数\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1开头典型的旧版 .doc 改名 .docx则改用 DOC 解析器避免把二进制 OLE 数据喂给 DOCX 解析器见 parser.py。两阶段流水线MarkdownParser 的组成docreader/parser/markdown_parser.py 中的MarkdownParser继承自PipelineParser将处理拆成两个串联阶段class MarkdownParser(PipelineParser): _parser_cls (MarkdownTableFormatter, MarkdownImageBase64)PipelineParserdocreader/parser/chain_parser.py实现了责任链模式每个子解析器依次处理前一个的输出文本各阶段产出的图片与元数据被累积合并进最终Document见 chain_parser.py。于是test.md的原始内容会依次经历MarkdownTableFormatter标准化全文所有表格对应test.md的包含表格章节MarkdownImageBase64提取图片并转为路径引用对应test.md的包含图片章节。而BaseParserdocreader/parser/base_parser.py定义了统一的契约parse_into_text(content: bytes) - Document输出 Markdown 文本与图片引用分块、OCR、VLM 图像描述均不在解析器职责内——这些由 Go 侧模块承担解析器只做文档 → Markdown 图片引用的轻量转换见 base_parser.py。Document模型docreader/models/document.py包含contentMarkdown 文本、images路径 → base64 数据、chunks、metadata四部分is_valid()以content ! 判定解析成功。表格标准化MarkdownTableUtil 的格式化规则test.md中第 2225 行的 GFM 表格在进入分块前先由MarkdownTableFormatter处理。其底层工具类MarkdownTableUtildocreader/parser/markdown_parser.py的format_table提供如下行为首尾管道规范化每行统一格式为| 单元格 | 单元格 |单元格两侧补空格例如|表头1|表头2|→| 表头1 | 表头2 |对齐标记保留分隔行的:位置会被保留并规范化为---如|:---|---:|:---:|原样保留左右/居中对齐语义format_alignment_row见 markdown_parser.py空单元格不丢失内部空单元格如| a | | c |在格式化后依然存在测试test_preserves_empty_cells明确断言formatted.count(|) raw.count(|)见 test_markdown_table_util.py行级处理、避免灾难性回溯format_table采用逐行扫描 仅处理首尾都有|的行替换了旧版正则实现——旧实现对未闭合行会触发指数级回溯Tencent/WeKnora#2768新实现将这类行原样透传测试test_malformed_unclosed_row_is_passthrough用 100 列的未闭合行验证不会卡死事件循环见 test_markdown_table_util.pyCRLF 归一化输入先做\r\n/\r→\n统一避免换行符混用导致表格行误判见 markdown_parser.py测试test_crlf_table_formats_without_mixed_endings验证输出不含\r且以\n结尾无表头表格补分隔行对 MarkItDown 产出的无表头表格自动在首行后插入| --- |分隔行保证 GFM 渲染器能将其识别为表格normalize_spurious_table_prefixes见 markdown_parser.py。对于test.md的标准表格格式化后输出形如| 表头1 | 表头2 | | --- | --- | | 内容1 | 内容2 | | 内容3 | 内容4 |图片与链接提取、解码与存储交接test.md的包含图片章节是MarkdownImageBase64的触发点。MarkdownImageUtildocreader/parser/markdown_parser.py提供三个关键方法extract_base64匹配alt形式的内嵌图片将其解码为二进制、用uuid4()生成唯一文件名保留原扩展名并把文档中的 base64 文本替换为alt路径引用解码失败时保留 alt 文本并记录 error 日志见 markdown_parser.py。MarkdownImageBase64解析器随后将这些二进制数据 base64 编码后放入Document.imagesextract_image提取普通图片路径alt支持通过path_prefix为相对路径添加前缀replaceFalse时可仅提取不替换见 markdown_parser.pyreplace_path根据旧路径 → 新 URL 的映射批量替换图片引用用于图片已上传、把本地路径替换为存储 URL的场景见 markdown_parser.py。值得注意的是docreader 侧不负责图片的最终持久化。gRPC 服务层 docreader/main.py 的_resolve_images将Document.images解码为ImageRef{filename, original_ref, mime_type, image_data}内联字节随响应返回由 Go App 侧负责写入 local/minio/cos/tos 等存储后端见 main.py。对于扫描件 PDF 这类图片量大的文档ReadStream流式 RPC 采用一帧一个图片的方式逐条发送避免整个响应超过 gRPC 消息大小上限见 main.py。test.md中的包含链接章节则无需特殊处理链接语法由分块阶段的保护正则兜底确保测试链接不会被从中间切开。分块与重叠TextSplitter 如何保持 Markdown 结构完整test.md最后两个章节明确声明了分块测试意图确保 Markdown 结构在分块时保持完整与在分块时与前后块重叠以确保上下文的连续性。这两条注释精准对应 docreader/splitter/splitter.py 中TextSplitter的两大机制保护正则protected_regex与重叠合并chunk_overlap。默认参数DEFAULT_CHUNK_OVERLAP 80 # 块间重叠字符数约为块大小的 15% DEFAULT_CHUNK_SIZE 512 # 每块最大字符数代码注释明确指出这两个默认值与 Go 侧生产路径 internal/infrastructure/chunker/splitter.go 的DefaultChunkSize 512、DefaultChunkOverlap 80对齐见 splitter.py 与 splitter.goPython 版 splitter 目前仅保留给 docreader 边车使用Go 版是生产主路径。512 字符约对应 100130 个英文 token 或约 300 个中文字符80 字符重叠约 15%是社区常用的上下文连续性经验值。保护正则先保结构再分块TextSplitter默认加载六条保护正则见 splitter.py保护对象正则对应 test.md 要素LaTeX 数学公式\$\$[\s\S]*?\$\$—Markdown 图片!\[.*?\]\(.*?\)测试图片Markdown 链接\[.*?\]\(.*?\)测试链接表格头含分隔行[ ]*(?:\|[^|\n]*)\|[\r\n]\s*(?:\|\s*:?-{3,}:?\s*)\|[\r\n]| 表头1 | 表头2 |表格体数据行[ ]*(?:\|[^|\n]*)\|[\r\n]| 内容1 | 内容2 |代码块头(?:\w)[\r\n][^\r\n]*python处理流程split_text见 splitter.py分五步_split按分隔符优先级默认[\n, 。, ]可按需扩展为\n\n、、等递归切分直到每片小于块大小切分时保留分隔符_split_protected用全部保护正则扫描匹配位置按起始位置升序、长度降序排序并过滤重叠超长保护内容会被忽略并记录 warning见 splitter.py_join把保护内容从相邻的普通分片中分离出来作为独立单元确保代码块、表格、链接等结构体在后续合并中不被拦腰截断并以assert .join(splits) text校验无损还原见 splitter.py_merge累积分片直到超出块大小然后从前端弹出元素直至剩余长度小于重叠值形成带重叠的新块见 splitter.py最终每个块输出(start_pos, end_pos, chunk_text)三元组restore_text可基于位置信息从带重叠的块中无损还原原文。表头追踪把上下文挂在块上_merge过程中还嵌入了HeaderTrackerdocreader/splitter/header_hook.py当检测到 Markdown 表格头表头行 分隔行模式或代码块起始时将这些表头作为上下文前缀注入到后续块中直到遇到空行或非表格内容才结束追踪同时通过header_column_mismatch校验表头列数与实际数据行列数列数不一致时立即结束追踪避免把错位的表头拼进无关块见 header_hook.py。因此test.md的每个##标题对应的表格、代码块、列表都能在分块后保留其所属章节的语义上下文。实操验证三条实测路径路径一本地脚本直跑不经过 gRPC在仓库根目录执行见 docreader/scripts/parse_local.pyPYTHONPATH. docreader/.venv/bin/python docreader/scripts/parse_local.py docreader/testdata/test.md脚本会将test.md解析为 Markdown 并打印到标准输出同时在 stderr 输出content_len、images数量、metadata与耗时统计。可用参数参数作用示例--engine选择解析引擎builtin / markitdown默认内置--engine markitdown--type指定文件类型默认按扩展名推断--type md--out将解析结果写入文件并导出图片到同目录images/--out /tmp/out.md--scanned扫描件 PDF 模式逐页渲染为图片--scanned--log-level日志级别DEBUG/INFO/WARNING/ERROR--log-level DEBUG对test.md而言解析后应看到标题层级完整保留、表格被格式化为规范 GFM 形式、测试图片语法保留原样外部链接图片不会被下载images计数为 0因为它是普通路径而非 base64 内嵌。路径二gRPC 服务 Go 客户端端到端测试先启动 DocReader 服务默认监听:50051支持 TLS见 docreader/main.pyPYTHONPATH. docreader/.venv/bin/python docreader/main.py再运行 docreader/client/client_test.go 中的端到端用例cd docreader/client go test -run TestReadFile -vTestReadFile会读取test.md内容、构造ReadRequest调用ReadRPC断言MarkdownContent非空并打印content_len与图片数见 client_test.go。若服务未启动测试会通过requireLiveDocReaderClient对localhost:50051的探测自动Skip。路径三Python 单元测试cd docreader .venv/bin/python -m pytest tests/test_markdown_table_util.py -v【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考