aksharaMD

align="center"> <img src="assets/logo.png" alt="AksharaMD" width="120" /> </p> <p align="center"> <a href://github.com/K2alyan/aksharaMD/actionsci.yml"><imgCI" src="https://github.com/K2alyan/aksharaMD/actions/workflows/ci.yml/badge.svg?branch=main"></a> <a href="https://pypi.org/project/aksharamd/"><img alt="PyPI" src="https://img.shields.io/pypi/v/aksharamd.svg?cacheSeconds=300"></a> <img alt="Python 3.11+"https://img/badge/python-3.11%2B-blue.svg"> <a href="LICENSE"><imgLicense: PolyForm NC" src="https://img.shields.io/badge/License-PolyForm%20NC-orange.svg"></a> </p> # AksharaMD **一款质量控制的LLM文档摄取管道。编译都会返回一个**0–100的AI就**和每个区块的提取置信度 - 就可以在LLM给出错误答案之前知道是否信任输出。 araMD接受任何文档 - PDF、DOCXLSX、音频、图像、存档等以上格式 - 并生成结构化、 token-efficient的Markdown直接馈送给LLM。目标不是源文件的品。目标是为LLM提供它恰好，以便在其上进行推理 - 成本仅为原始小部分 - 同时提供明确的信号，表明提取如何。 完全在设备上运行。无需云调用，无离开您的机器，无需API密钥。 --- ## 为什么选择AksharaMD ### 没有解析器能解决的问题：您不知道输出是否值得信赖 每个解析器都返回文本。它们中没有一个能告诉您该文本是否足够可靠以嵌入。扫描的PDF、包含大量表格的报告或具有OCR乱码的文档可能会产生看起来完整的输出 - 直到LLM回答错误。届时，错误的数据已经在您的向量存储中了。 AksharaMD在内容旁边生成质量信号： - **AI就绪分数0–100**，具有质量等级 - 高（≥85）/ 良好（≥70）/ 有风险（≥50）/ 差劲（<50）- 每次编译都会生成 - **每个区块的提取置信度** - 每个区块都被标记为EXTRACTED、INFERRED或AMBIGUOUS，然后再送到嵌入器 - **命名警告** - `OCR_REQUIRED`、`LOW_TEXT_DENSITY`、`GLYPH_ARTIFACTS`、`REPEATED_CONTENT`等五个警告 - 准确告诉您问题出在哪里以及如何修复 - **当提取不可靠时，分数会自动下降** - 无需手动检查 ### token问题 每种格式也会以不同的方式浪费token：PDF有页眉、页脚、水印和扫描页；DOCX有修订历史和嵌入元数据；XLSX有数千个空单元格。AksharaMD在LLM看到它们之前会剥去所有这些。剩下的内容是结构化的，包括标题、表格和代码块 - 仅为原始token成本的一小部分。 - **比[MarkItDown](https://github.com/microsoft/markitdown)在等效文档上少15倍token** - 跨23种格式类型进行测量 - **少98.5%噪音** - 3.7平均噪音行与MarkItDown的250.1行相比 - **比[Docling](https://github.com/DS4SD/docling)在PDF上快27倍，质量相当** - **结构化输出** - 真正的标题、表格、代码块；不是纯文本 - **无ML依赖** - 快速、内存高效、确定性且完全可复制 - **完全本地** - 无云API，无文档上传，无数据保留问题 --- ## 快速入门 需要 **Python 3.11 或更高版本**。 ```bash pip install aksharamd aksharamd compile report.pdf aksharamd validate report.pdf aksharamd formats ``` 输出写入 `output/report/`： ``` output/report/ ├── # 编译 ├── document.json # 结构化区块模型 ├── manifest.json # token计数、计时、就绪分数 ├── validation.json # 提取问题 └── chunks/ # 语义区块的JSON ``` **扫描的PDF**（需要系统级安装Tesseract 5+ - `pip install`不足以完成此操作）： ```bash pip install "aksharamd[ocr]" # 单独安装Tesseract 5+：https://github.com/tesseract-ocr/tesseract # 确保tesseract二进制文件在您的PATH中，然后： aramd compile scanned.pdf ``` **Claude Desktop（MCP）：** ```bash aksharamd-config --write # 重启Claude DesktopsharaMD将出现在工具面板中 ``` --- ```bash # 标准安装 pip installaramd # 带有图像OCR（需要T 参见下文） pip install "aksharamd[ocr]" 带有音频转录（需要ffmpeg在PATH中） pip install "aksharamd[audio]" # 带有S3输入支持（s3://bucket/key URIs） pip install "akd[cloud] 所有功能 pip install "aksharamd]" ``` 从源代码安装： ```bash git clone https://github.com/K2alyan/aksharaMD.git cd aksharaMD pip install -e . ``` **可选系统依赖：** | 功能 | 需求 | |---------|-------------| | 图像OCR | [Tesseract 5+](https://github.com/tesseract-ocr/tesseract) 二进制文件在PATH中，然后 `pip install "aksharamd[ocr]"` | | 音频转录 | [ffmpeg](https://ffmpeg.org) 在PATH中，然后 `pip install "aksharamd[audio]"` | | S3输入（`://` URIs） | `pip install "aksharamd[cloud]"` - 无系统二进制文件需求 | | 传统Office（`.doc`，`.ppt`） | [LibreOffice](https://www.libreoffice.org) 在PATH中 | | Pandoc | [Pandoc](https://pandoc.org/installing.html) 二进制文件中 - 启用AsciiOrg-mode、Textile、MediaWiki、DocBook、man/roff和OPML | --- ## 已知限制 核心管道在118种文件扩展名上稳定且经过生产测试，但在使用生产工作流程之前，请注意以下几点。 **扫描的PDF的OCR需要系统二进制文件。** `pip install "aksharamd[ocr]"`安装Python包装器（`pytesseract`）但不是Tesseract本身。您还必须在操作系统级别安装[Tesseract 5+](https://github.com/tesseract-ocr/tesseract)并确保`tesseract`二进制文件在您的`PATH`中。没有它，扫描页面会产生差劲的分数和`OCR_REQUIRED`警告。 **复杂的PPTX布局得到支持但仍处于实验阶段。** 标准幻灯片内容、项目符号和嵌入表格可靠地提取。复杂的动画、大量分层的幻灯片母版和自定义布局模板可能会产生不完整的输出。 **.的置信度低于EML/DOCX/PDF。** `.msg`格式是一种专有二进制容器。大多数情况下， 正文和附件正确提取，但嵌入的日历对象、富文本编码边缘情况和S/MIME签名消息可能无法完全解析。 **Windows：请使用Windows Terminal或PowerShell 7。** 旧版`cmd.exe`使用cp1252代码页，无法渲染CLI输出中使用的某些Unicode字符（例如Rich使用的绘图线）。在[Windows Terminal](https://aka.ms/terminal)、VS Code的集成终端或PowerShell 7中运行AksharaMD。设置`PYTHONUTF8=1`也可以解决大多数编码问题。 **`mcp-config --write`会创建自动备份。** 在覆盖Claude Desktop配置之前，AksharaMD会保存一个带有时间戳的副本（例如`claude_desktop_config.1720123456.bak.json`）在同一目录中。不会丢失数据，但您可能需要在确认新配置有效后手动清理这些文件。 --- ## CLI参考 ### `compile` 将文档或URL编译为Markdown、JSON和语义区块。 ```bash aksharamd compile <source> [options] ``` | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `-o`, `--output` | `output` | 输出目录 | | `--timings` | — | 显示每个阶段的计时明细 | | `--quiet` | — | 禁止所有控制台输出 | | `-v`, `--verbose` | — | 启用调试日志记录 | **示例：** ```bash # 编译本地文件 aksharamd compile report.pdf # 指定输出目录 aksharamd compile report.pdf -o compiled/ # 编译URL aksharamd compile https://arxiv.org/pdf/2301.00001 # 显示计时明细 aksharamd compile report.pdf --timings # 禁止输出（用于脚本编写） aksharamd compile report.pdf --quiet ``` ### `validate` 在不写入输出文件的情况下验证提取。 ```bash aksharamd validate report.pdf aksharamd validate https://example.com/doc.pdf ``` 成功退出状态为`0`，如果找到验证错误，则退出状态为`1`。 ### `benchmark` 编译多个文件并比较它们。 ```bash aksharamd benchmark doc1.pdf doc2.docx doc3.html ``` ### `stats` 显示跨所有编译的累计token节省。 ```bash aksharamd stats aksharamd stats --reset # 清除账本 ``` ### `show-manifest` 打印先前编译的清单。 ```bash aksharamd show-manifest output/report/ ``` ### `corpus` 编译目录下的每个支持文件为token预算绑定区块，并具有自动近重复检测。 ```bash aksharamd corpus <source_dir> [options] ``` | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `-o`, `--output` | — | 将区块写入JSON文件 | | `--budget` | `60000` | 每个区块的最大token数 | | `--dedup-threshold` | `0.5` | 近重复跳过的Jaccard相似度阈值 | ```bash aksharamd corpus ./documents/ --budget 8000 -o corpus.json ``` ### `mcp-config` 为Claude Desktop生成并应用MCP服务器配置。 ```bash aksharamd mcp-config # 打印配置以手动复制 aksharamd mcp-config --write #Claude Desktop配置 ``` ### `formats` 列出所有已注册器和支持的扩展名。 ```bash aksharamd formats ``` --- ## Python API ### 编译为字符串 在不将任何文件写入磁盘的情况下编译文档。 ```python from aksharamd.compiler import Compiler compiler = Compiler(output_dir="output") text, ctx = compiler.compile_to_string("report.pdf") print(text) # 编译后的Markdown print(ctx.manifest.optimized_tokens) # 优化后的token计数 print(ctx.manifest.token_reduction_percent) # 与原始token相比的百分比减少 print(ctx.manifest.readiness_score) # 置信度0-100 print(ctx.manifest.elapsed_seconds) # 墙上时钟时间 ``` ### 完整编译（写入磁盘） ```python ctx = compiler.compile("report.pdf") # 输出写入output/report/document.md、manifest.json等。 ``` ### 从URL编译 ```python text, ctx = compiler.compile_to_string("https://arxiv.org/pdf/2301.00001") ``` ### 流式传输区块 在不等待整个文档的情况下，处理区块的提取和优化。适用于馈送RAG索引、向量存储或可以处理单个区块的任何管道。 ```python from aksharamd.compiler import Compiler from aksharamd.models.block import BlockType compiler = Compiler() for block in compiler.stream("report.pdf"): if block.type == BlockType.TABLE: index_table(block.content) elif block.type == BlockType.PARAGRAPH: embed_and_store(block.content) ``` `stream()` 运行 detect → parse → clean → optimize 并在文档顺序中产生每个 `Block`。验证、区块、清单和导出阶段被跳过 - 当您需要这些时，请使用 `compile()`。 ### 多模态输出（内联图像） 返回一个与Anthropic兼容的内容数组，包含文本和base64图像交错在文档位置。 ```python content, ctx = compiler.compile_to_multimodal("report.pdf") # 直接传递给Anthropic API response = anthropic_client.messages.create( model="claude-opus-4-7", max_tokens=4096, messages=[{"role": "user", "content": content + [{"type": "text", "text": "Summarise this."}]}], ) ``` ### 编译上下文 所有编译方法返回的 `ctx` 对象公开： | 属性 | 类型 | 描述 | |-----------|------|-------------| | `manifest.source` | `str` | 源文件路径或URL | | `manifest.file_type` | `str` | 检测到的格式 | | `` | `int` | 页面或章节计数 | | `manifest.original_tokens` | `int` | 原始token估计 | | `manifest.optimized_tokens` | `int` | 管道后的token | | `manifest.token_reduction_percent` | `float` | 减少百分比 | | `manifest.readiness_score` | `int` | 提取置信度0-100 | | `manifest.elapsed_seconds` | `float` | 墙上时钟时间 | | `manifest.tables` | `int` | 提取的表格 | | `manifest.chunks` | `int` | 产生的语义区块 | | `` | `list` | 提取错误（如果有） | | `validation.warnings` | `list` | 非致命问题 | | `document.blocks` | `list[Block]` | 结构化区块模型 | --- ## MCP服务器 AksharaMD附带一个](https://modelcontextprotocol.io)服务器，作为任何MCP兼容主机（Claude Desktop、Cursor等）的工具公开编译管道。 ### 设置 安装后运行此命令： ```bash aksharamd mcp-config --write ``` 这会检测您的Python环境，生成正确的配置，并直接写入Claude Desktop配置文件。重启Claude Desktop - AksharaMD将出现在工具面板中。 要预览配置后再写入： ```bash aksharamd mcp-config ``` ### 克劳德中的工具 | 工具 | 描述 | |------|-------------| | `compile_document` | 编译任何文件或URL为干净的Markdown | | `compile_document_multimodal` | 编译带有内联图表和图表 | |_formats 列出所有支持和可选依赖 `get_stats` | 跨编译的生命周期token节省 | ### HTTP模式（服务器部署）Claude通过网络连接而非启动本地进程的部署： ```bash AKSHARAMD_MCP_API_KEY=your-secret-key \ AKSHARAMD_ALLOWED_ROOT=//allowed/documents \ aksharamd-mcp --transport streamable-http --host 0.0.0.0 --port 8000 AKSHARAM_ROOT` 限制服务器可以读取的目录。`AKSHARAMD_MCP_API_KEY` 需要客户端在每个请求中发送 `X-API-Key` 头部。两者在本地stdio模式下都是可选的，但在HTTP模式下强烈建议使用。 --- ## 生态系统 AksharaMD作为**文档摄取层**运行 - 它处理格式转换、噪音移除、重复数据删除和语义分块，以便下游工具接收干净的结构化文本。它与以下系统自然集成。 ### Lang用AksharaMD的提取管道替换LangChain的内置文档加载器（`PyPDFLoader`、`UnstructuredFileLoader`等）。输出直接映射到`langchain_core.documents.Document`。在嵌入之前检查就绪分数 - 跳过或标记评级有风险或较差的文档。 ```python aksharam import Compiler chain_core.doc Document compiler =, ctx.compile_to_string("report.pdf") # 在向量存储到达之前跳过的提取 ifanifest.readiness_score < 50: print(f"提取不良 ({ctx.manifest.read}/100)过嵌入") in ctx.validation.warnings: print [{w.code}] {w.message}") else: doc = page_content=text, metadata "source": ctx.manifest.source "file_type": ctx.manifest.file_type, "readiness_score":anifest_score, "quality_band": ctx.manifest.quality_band, / OK / RISKY / POOR "page_count":anifest.pages, }, ) ``` ### LlamaIndex 在LlamaIndex的索引和检索管道之前，使用AksharaMD作为文档读取器，替换`SimpleDirectoryReader`以实现对复杂格式的高保真提取。 将就绪分数存储为元数据，以便检索结果可以按提取质量过滤。 ```python from aksharamd.compiler import Compiler from llama_index.core import Document, VectorStoreIndex compiler = Compiler() text, ctx =_to_string("report.pdf") index = VectorStoreIndex.from_documents([ Document( text=text, metadata={ "source": ctx.manifest.source, "readiness_score": ctx.manifest.readiness_score, "quality_band": ctx.manifest.quality_band, }, ), ]) ``` ### 向量存储（ChromaDB、Pinecone、Weaviate、Qdrant） `compile_corpus()`遍历目录，将相似的文档通过MinHash LSH去重，并返回可嵌入和插入的token预算绑定区块。`token_budget`参数应设置为嵌入模型的上下文窗口大小。 ```python from aksharamd.compiler import Compiler compiler = Compiler() chunks = compiler.compile_corpus("./documents", token_budget=8_000, dedup_threshold=0.8) for chunk in chunks: texts = [doc["text"] for doc in chunk["documents"]] ids = [doc["source"] for doc in chunk["documents"]] collection.add(documents=texts, ids=ids) ``` 每个区块都带有`confidence`分解（`extracted`、`inferred`、`ambiguous`区块计数），可以作为元数据存储，并用于按提取质量过滤检索结果。 ### Graphify AksharaMD旨在作为知识图构建管道（如[Graphify](https://github.com/safishamsi/graphify)）的前置处理层。Graphify期望连贯的文本段作为输入；AksharaMD处理将这些文本从任意文档格式中提取出来的上游问题，包括扫描的PDF、存档和旧版Office文件。 这两个工具共享相同的MinHash签名族（Mersenne-prime universal hashing），因此在AksharaMD阶段应用的近重复检测不需要在下游重复。 ```python from aksharamd.compiler import Compiler compiler = Compiler() chunks = compiler.compile_corpus( "./documents", token_budget=60_000, # 将区块大小调整为Graphify的首选上下文窗口 dedup_threshold=0.8, ) for chunk in chunks: combined_text = "\n\n---\n\n".join(doc["text"] for doc in chunk["documents"]) graph_builder.ingest(combined_text) ``` ## 支持的格式 | 类别 | 扩展名 | |----------|------------| | 文本和标记 | `.md` `.txt` `.rst` `.tex` `.html` `.htm` | | 文档 | `.pdf` `.docx` `.pptx` `.xlsx` `.odt` `.ods` `.odp` `.epub` `.rtf` | | 旧版 Office | `.doc` `.ppt` `.xls` *(需要 PATH 中的 LibreOffice)* | | 数据 | `.json` `.jsonl` `.csv` `.tsv` `.xml` `.yaml` `.toml` | | 电子邮件 | `.eml` `.msg` | | 笔记本 | `.ipynb` | | 源代码 | `.py` `.js` `.ts` `.go` `.rs` `.java` `.c` `.cpp` `.sql` `.sh` 及 30 多种其他格式 | | 图片 (OCR) | `.jpg` `.jpeg` `.png` `.tiff` `.bmp` `.webp` `.gif` *(需要 Tesseract)* | | 音频 | `.mp3` `.wav` `.m4a` `.ogg` `.flac` *(需要 Whisper + ffmpeg)* | | 归档文件 | `.zip` `.tar` `.tgz` `.gz` `.bz2` `.xz` `.7z` | | 源信息流 | `.rss` `.atom` | --- ## 基准测试 这些是两项独立的研究。第一项研究在小型内部语料库上衡量 token 效率和速度。第二项研究衡量 token 节省是否真正能产生更好的 LLM 答案，使用更大的独立语料库和 LLM 评估器。 --- ### 研究 1 — token 效率和速度 **语料库：** 101 篇文档，跨 23 种格式类型（内部生产语料库，2026 年 6 月）。PDF 子表格使用 20 篇文档的 arXiv/技术报告子集，其中也评估了 Docling。 #### PDF（20 篇文档 - arXiv 论文，技术报告） | 指标 | AksharaMD | MarkItDown | Docling | |--------|-----------|------------|---------| | 平均 token 数 | **12,608** | 24,506 | 15,049 | | 质量分数 | **94.1** | 92.8 | 93.0 | | 平均时间 | **1.09s** | 1.64s | 29.96s | AksharaMD 在 PDF 上比 Docling **快 27 倍**，质量相当，且 token 比 MarkItDown **少 49%**。 #### 所有格式（101 篇文档，23 种类型） | 指标 | AksharaMD | MarkItDown | |--------|-----------|------------| | 平均 token 数 | **21,199** | 331,171 | | 平均噪音行数 | **3.7** | 250.1 | | 平均时间 | 1.40s | 0.48s | | 涵盖的格式类型 | **23** | 16 | AksharaMD 在整个语料库中生成的 **token 少 15 倍**，**噪音减少 98.5%**。MarkItDown 在简单格式上更快；AksharaMD 由于更深入的提取（结构检测、重复数据删除、切分）而较慢。 #### 按格式划分的质量分数 | 格式 | AksharaMD | MarkItDown | |--------|-----------|------------| | HTML | **98.2** | 93.4 | | JSON | **98.8** | 43.5 | | RSS / ATOM | **95.1** | 93.6 | | CSV | **93.8** | 80.0 | | XLSX | 80.0 | 80.0 | | PPTX | 72.5 | 81.0 | 具有独家支持的格式（MarkItDown 不处理）：`.zip`、`.tar`、`.7z`、`.jsonl`、`.xml`、`.rss`、`.atom`、`.eml`、`.rtf`、`.ipynb`、`.odt`、`.ods`、`.odp`，通过 LibreOffice 支持旧版 Office。 --- ### 研究 2 — 下游 LLM 准确性 **语料库：** 约 1,000 篇文档，跨 12 种格式（每种格式 83 篇文档）- 与研究 1 独立的单独数据集。 token 效率是必要的，但不是充分的 - 清洁提取仅在它产生更好的 LLM 答案时才有意义。我们使用分层语料库测试了这一点，该语料库涵盖了企业工作负载中发现的完整复杂性范围。文档按三个层级选择 - 按照 [DocBank](https://github.com/doc-analysis/DocBank) 和 [PubLayNet](https://github.com/ibm-aur-nlp/PubLayNet) 等文档 AI 基准测试中使用的分类法： | 层级 | 描述 | 示例格式 | |------|-------------|-----------------| | **简单** | 单列文本，最少格式化 | 普通文本，CSV，JSON，电子邮件 | | **结构化** | 多节包含表格和嵌入元素 | DOCX，XLSX，PPTX，EPUB | | **复杂** | 布局密集，混合媒体 | 多列学术 PDF，Jupyter 笔记本，混合格式存档 | 每篇文档收到 4 个事实问题，由所有 5 种工具独立回答，由 Claude Haiku 4.5 作为评估器评分（0-10）（总共 19,920 个评估答案）。未应用工具特定提示调优。 | 工具 | 平均分数 | 平均 token 数 | 涵盖格式 | |------|:---------:|:----------:|:---------------:| | **AksharaMD** | **9.5/10** | **6,272** | **12/12** | | [MarkItDown](https://github.com/microsoft/markitdown) | 8.6/10 | 27,449 | 12/12 | | [Docling](https://github.com/DS4SD/docling) | 8.6/10† | 35,461 | 8/12 | | [PyMuPDF4LLM](https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/) | 8.0/10† | 34,231 | 8/12 | | [LlamaParse](https://github.com/run-llama/llama_parse) | 7.8/10 | 26,274 | 12/12 | † 准确性仅在支持的格式上衡量（Docling 不支持 EML、IPYNB、JSON 和 XML；PyMuPDF4LLM 不支持 EML、IPYNB、CSV 和 JSON）。 AksharaMD 比每种竞争工具 **节省 76-82% 的 token**，同时领先于准确性 - 并且是唯一一种涵盖所有 12 种格式类型的工具。在 100,000 篇文档/月的用量下，这相当于 **节省 1,600-2,335 美元的 API 费用**（Claude Haiku 4.5 定价）。 ### 自托管模型吞吐量 token 节省在自托管模型上是复合的。KV-cache VRAM 是并发请求能力的约束，prefill attention FLOPs 在序列长度上为 O(n²)。 | 部署场景 | AksharaMD | MarkItDown | 吞吐量增益 | |---------------------|:---------:|:----------:|:---------------:| | 8B int4 · RTX 4090 (24 GB) | **25** 并发 | 5 并发 | **5.0×** | | 70B int4 · A100 80 GB | **20** 并发 | 4 并发 | **5.0×** | MarkItDown 的平均上下文 **比 AksharaMD 长 19 倍**，在同一 GPU 上 - 差异在 0.3 秒和 ~6 秒的时间到第一个 token 之间。 有关完整的方法论、按格式划分的分数、成本表、自托管吞吐量分析和复制说明，请参见 [`benchmarks/LLM_QA_BENCHMARK.md`](benchmarks/LLM_QA_BENCHMARK.md)。 --- ## 架构 ``` 检测 → 解析 → 清洁 → 优化 → 验证 → 切分 → 分词 → 清单 → 评分 → 导出 ``` 每个阶段接收并返回一个 `CompilationContext` 对象。阶段是独立可插拔的。 ``` aksharamd/ ├── compiler.py # 协调 10 个阶段的管道 ├── context.py # CompilationContext - 跨阶段共享状态 ├── cli.py # 基于 Click 的 CLI（编译、验证、基准测试、语料库、统计、mcp-config） ├── mcp_server.py # FastMCP 服务器（4 个工具） ├── ledger.py # 持久化节省账本（~/.aksharamd/ledger.jsonl） ├── scoring/ │ └── readiness.py # 提取置信度评分（0-100） ├── models/ # Pydantic v2 模型（Manifest、Document、Block、Chunk、Asset） └── plugins/ ├── parsers/ # 格式特定的提取器（40 多种格式） ├── cleaners/ # 重复数据删除、噪音移除、空格归一化 ├── optimizers/ # token 减少传递 ├── chunkers/ # 语义切分 ├── exporters/ # Markdown 和 JSON 序列化 └── validators/ # 模式和内容验证 ``` **插件注册** 使用副作用导入 - 解析器在模块加载时注册自己。添加新格式只需要一个类和一个 `register_parser("ext", MyParser)` 调用。 --- ## 已知限制 这些是系统的当前边界。它们不是错误。 **扫描/图像密集型 PDF。** AksharaMD 对图像页面应用 Tesseract OCR，但复杂的 multicolumn 布局、旋转文本或低分辨率扫描将比视觉-LLM 方法（[olmOCR](https://github.com/allenai/olmocr)，[Docling](https://github.com/DS4SD/docling) 使用 VLM 模式）产生更低保真度的输出。如果您的语料库主要是扫描文档，请仔细评估。 **旧版 Office 格式（`.doc`，`.ppt`）。** 解析需要系统 PATH 中的 LibreOffice 进行格式转换。如果 LibreOffice 不存在，则这些文件会以明确的错误被拒绝。`.docx`，`.pptx` 和 `.xlsx` 没有此类依赖。 **音频转录。** 质量取决于 Whisper 模型大小（默认为 `base`）。设置 `AKSHARAMD_WHISPER_MODEL=large-v3` 以获得更高的准确性，但速度会降低。需要 ffmpeg。 **大文件。** 默认情况下，超过 500 MB 的文件被拒绝。如果需要，可以使用 `AKSHARAMD_MAX_FILE_BYTES` 提高限制。 **没有 MCP 流式传输。** CLI 显示实时进度旋转器，`Compiler.stream()` 为程序调用者逐步生成块（RAG 索引、管道）。MCP `compile` 工具仍然完整地返回整个文档 - MCP 消费者流式传输块的路线图。 **没有结构化日志记录。** 日志输出为纯文本。每个请求的跟踪 ID、JSON 格式日志和 Prometheus 指标（请求数、延迟直方图、token 节省计数器）是 HTTP MCP 服务器部署路径的路线图。 **复杂的跨行表格标题。** 具有合并单元格或多行标题的财务表格可能会产生列名伪影（`Col1`，`Col2`）。表格内容被保留；仅标题行受到影响。 --- ## 贡献 欢迎提交错误报告和拉取请求。请先打开一个问题来讨论重大更改。 --- ## 许可证 [PolyForm 非商业 1.0.0](LICENSE) - 免费用于个人和非商业用途。如需商业许可，请在此仓库中打开一个问题。