# Chandra OCR入门指南：CLI命令参数详解（--output-format, --batch-size等） ## 1. 引言：为什么你需要Chandra OCR？ 如果你经常需要处理扫描的PDF、合同、学术论文或者带表格的图片，并且希望把它们转换成可以直接编辑、搜索的格式，那么你很可能遇到过传统OCR工具的痛点：转换出来的文字一团糟，表格没了，公式乱了，排版信息全丢，最后还得花大量时间手动整理。 今天要介绍的Chandra OCR，就是为了解决这个问题而生的。它不是一个普通的OCR工具，而是一个“布局感知”的智能模型。简单来说，它不仅能认出图片里的文字，还能理解这些文字是怎么排版的——哪里是标题，哪里是段落，表格有几行几列，公式长什么样——然后把这些信息完整地保留下来，直接输出成结构清晰的Markdown、HTML或者JSON。 最吸引人的是，它开箱即用。你不需要懂复杂的深度学习，只需要在命令行里敲几个命令，就能把一堆图片或PDF变成整齐的文档。这篇文章，我就带你从零开始，手把手掌握Chandra OCR最核心的CLI（命令行界面）使用方法，特别是那些能让你事半功倍的关键参数。 ## 2. 快速开始：安装与你的第一次OCR 在深入参数之前，我们先确保你能把工具跑起来。整个过程非常简单。 ### 2.1 环境准备与安装 Chandra OCR推荐使用vLLM作为推理后端，这能获得更好的性能和GPU利用率。假设你有一台带NVIDIA显卡的电脑（显存建议4GB以上），跟着下面几步走： 1. **创建并激活虚拟环境**（可选但推荐）： ```bash # 使用conda conda create -n chandra-env python=3.10 conda activate chandra-env # 或者使用venv python -m venv chandra-env source chandra-env/bin/activate # Linux/Mac # chandra-env\Scripts\activate # Windows ``` 2. **安装vLLM和Chandra OCR**： 官方推荐先安装vLLM，再安装Chandra。一条命令搞定： ```bash pip install vllm chandra-ocr ``` 安装过程会自动处理所有依赖。如果遇到网络问题，可以考虑使用国内的镜像源。 ### 2.2 你的第一个OCR命令 安装成功后，打开终端，尝试处理一张图片： ```bash chandra ocr --input-path ./your_image.jpg --output-dir ./results ``` 把 `./your_image.jpg` 换成你电脑上任意一张包含文字的图片路径（比如截图、扫描件）。运行后，Chandra会开始处理，并在 `./results` 目录下生成结果。 默认情况下，它会生成三种格式的文件：`.md` (Markdown)、`.html` 和 `.json`。打开那个 `.md` 文件看看，你会发现文字不仅被提取出来了，连基本的段落、标题结构都保留着。 恭喜，你已经成功运行了Chandra OCR！但这只是开始。接下来，我们看看如何通过命令行参数，让它变得更强大、更符合你的需求。 ## 3. 核心参数详解：掌控输出与性能 Chandra OCR的CLI提供了丰富的参数，这里我们重点剖析几个最常用、最能影响结果和效率的核心参数。 ### 3.1 输出控制参数：`--output-format` 这是你最先需要关注的参数之一。它决定了Chandra给你什么格式的结果。 * **作用**：指定输出文件的格式。 * **用法**： ```bash chandra ocr --input-path doc.pdf --output-format markdown ``` * **可选值**： * `markdown`：生成 `.md` 文件。这是最通用的格式，适合导入到笔记软件（如Obsidian、Notion）、博客系统或版本控制中。它会用 `#`、`##` 表示标题，用 `|` 绘制表格，用 `$$` 包裹公式。 * `html`：生成 `.html` 文件。适合直接嵌入网页或需要精确样式还原的场景。HTML能保留更丰富的结构信息。 * `json`：生成 `.json` 文件。这是一种机器友好的格式，包含了最完整的结构化信息，比如每个文本块的坐标、类型（标题、段落、表格单元格等）。适合后续用程序进行自动化处理或分析。 * `all`：**默认值**。同时生成上述三种格式的文件。对于探索性工作，用这个选项最省心。 **怎么选？** * 只想快速查看和编辑文字内容，选 `markdown`。 * 需要把结果放到网站上，选 `html`。 * 你要写个程序，自动从OCR结果里抽表格数据，选 `json`。 * 还不确定后续怎么用，或者都想保留一份，就用 `all`。 ### 3.2 性能与效率参数：`--batch-size` 当你需要处理大量文件时（比如一个文件夹里有上百张图片），这个参数能极大提升速度。 * **作用**：指定一次同时处理多少个文件。增大批次大小可以利用GPU的并行计算能力，减少整体处理时间。 * **用法**： ```bash chandra ocr --input-path ./images_folder/ --batch-size 4 ``` * **工作原理**：GPU擅长同时做很多相同的计算。`batch-size=1` 是一次处理1个文件，处理完再处理下一个。`batch-size=4` 是一次把4个文件的数据打包送给GPU，GPU同时处理这4个，效率更高。 * **如何设置**： * 这个值不是越大越好。它受限于你的**GPU显存**。 * 对于包含复杂版面、高分辨率图片的文件，每个文件需要更多显存。 * **建议**：从较小的值开始（如2或4），逐步增加，同时用 `nvidia-smi` 命令监控GPU显存使用情况。如果显存快满了，就不要再增加了。对于RTX 3060（12GB显存），处理普通文档，设置 `--batch-size 4` 或 `8` 通常比较安全。 ### 3.3 输入与输出路径参数 这两个参数虽然简单，但组合使用能应对各种复杂情况。 * `--input-path`：指定输入源。 * 可以是一个**文件**：`./合同扫描件.pdf` * 可以是一个**文件夹**：`./所有扫描图片/` （Chandra会自动识别文件夹内的图片和PDF） * 甚至可以使用通配符：`./images/*.png` （处理所有png图片） * `--output-dir`：指定输出目录。 * 所有生成的结果文件（.md, .html, .json）都会放在这个目录下。 * 每个输入文件会生成一个对应的结果文件，文件名保持一致，只改后缀。 * 例如：处理 `发票.jpg`，会在输出目录生成 `发票.md`、`发票.html`、`发票.json`。 **实用例子**：处理整个项目文件夹的扫描件，并统一输出到`ocr_results`里。 ```bash chandra ocr --input-path ./project_docs/ --output-dir ./ocr_results --output-format markdown ``` ## 4. 进阶参数与实用技巧 掌握了核心参数，你已经能解决80%的问题。下面这些参数能帮你处理更特殊的场景。 ### 4.1 处理特定页面：`--pages` 当你有一个几百页的PDF，但只需要其中几页时，这个参数能节省大量时间。 * **作用**：指定需要处理的PDF页面范围。 * **用法**： ```bash # 只处理第5页 chandra ocr --input-path report.pdf --pages 5 # 处理第1到第10页 chandra ocr --input-path report.pdf --pages 1-10 # 处理第1，3，5页 chandra ocr --input-path report.pdf --pages 1,3,5 # 处理第5页到最后一页 chandra ocr --input-path report.pdf --pages 5- ``` ### 4.2 语言提示参数：`--language` 虽然Chandra能自动检测多种语言，但如果你明确知道文档的主要语言，告诉它能提升识别准确率，尤其是对混合语言文档。 * **作用**：为模型提供语言提示。 * **用法**： ```bash chandra ocr --input-path document.jpg --language “zh” # 中文 chandra ocr --input-path document.jpg --language “en” # 英文 chandra ocr --input-path document.jpg --language “ja” # 日文 ``` * **支持的语言代码**：非常多，常见如 `zh` (中文)、`en` (英文)、`ja` (日文)、`ko` (韩文)、`de` (德文)、`fr` (法文)等。查看官方文档可获得完整列表。 ### 4.3 模型选择与设备参数 * `--model-name-or-path`：如果你下载了官方的模型权重到本地，可以用这个参数指定本地路径，避免每次从网络加载。对于内网或无网环境特别有用。 ```bash chandra ocr --input-path doc.jpg --model-name-or-path ./models/chandra-ocr-weights/ ``` * `--device`：强制指定运行设备。虽然vLLM通常会自动选择GPU，但在特殊情况下（比如想用CPU跑一个小测试），可以指定 `--device cpu`。注意，CPU速度会慢很多。 ## 5. 综合实战：一个完整的处理流程 现在，我们把所有参数组合起来，看一个处理真实任务的例子。 **任务**：你有一个 `financial_reports.pdf` 文件，共50页。你只需要分析其中的第10-15页（包含一些关键财务报表）。这些报表是中英文混合的，你希望以Markdown格式输出，方便后续整理，并且希望处理速度尽可能快。你的显卡是RTX 4060（8GB显存）。 **步骤**： 1. **创建输出目录**（可选）： ```bash mkdir -p ./output_financial ``` 2. **构建命令**： 我们需要组合以下参数： * `--input-path`：指定PDF文件。 * `--pages`：指定10-15页。 * `--language`：给出语言提示“zh”（因为以中文为主）。 * `--output-format`：指定输出Markdown。 * `--output-dir`：指定输出目录。 * `--batch-size`：为了加快速度，根据显存情况，设置为4。 **完整命令**： ```bash chandra ocr \ --input-path ./financial_reports.pdf \ --pages 10-15 \ --language “zh” \ --output-format markdown \ --output-dir ./output_financial \ --batch-size 4 ``` 3. **运行与检查**： 在终端执行上述命令。处理完成后，进入 `./output_financial` 目录，你会看到 `financial_reports.md` 等文件。打开Markdown文件，你会发现第10-15页的内容已经被清晰地转换出来，表格应该也以Markdown表格的形式完美呈现了。 ## 6. 总结 通过这篇指南，你应该已经掌握了Chandra OCR CLI工具的精髓。我们来快速回顾一下要点： 1. **安装简单**：`pip install vllm chandra-ocr` 就能搞定，对新手极其友好。 2. **核心参数三剑客**： * `--output-format`：控制你要Markdown、HTML还是JSON。**日常用`markdown`，编程处理用`json`，不确定就选`all`**。 * `--batch-size`：提升批量处理速度的关键。**根据你的GPU显存从2或4开始尝试**。 * `--input-path` 和 `--output-dir`：管理你的输入输出，支持文件和文件夹。 3. **进阶技巧**： * 用 `--pages` 处理PDF的特定页面，省时省力。 * 用 `--language` 给模型一点提示，在混合语言文档上效果更好。 4. **组合使用**：像第5节中的实战例子一样，根据你的具体任务，灵活组合这些参数，让Chandra OCR为你高效工作。 Chandra OCR的强大之处在于，它把复杂的AI模型封装成了一个简单的命令行工具。你不需要关心背后的技术细节，只需要记住这几个参数，就能把堆积如山的扫描件、PDF，变成结构清晰、可直接利用的数字文档。现在就找一些你的文件试试吧，从简单的图片开始，逐步应用到更复杂的场景中。 --- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。