百度 Unlimited-OCR Skill

一个可直接安装到 Codex 的文档 OCR Skill，也可以脱离 Codex 作为命令行工具使用。它调用百度智能云 Unlimited-OCR 异步接口，将图片、PDF、Office 文档和扫描件输出为 Markdown 与结构化 JSON。

能力

• 图片、PDF、OFD、Word、PPT、TXT 等文件识别
• Markdown 输出，保留公式、表格和版面结果（具体能力以百度接口返回为准）
• 结构化 JSON 输出
• 单文件、目录批量、递归目录、公网 URL 三种输入方式
• 自动轮询、重试、结果下载、批量汇总
• 用户级 token 缓存，不写入安装目录
• --json 机器可读输出，适合 Codex、脚本和 CI
• ocr_doctor.py 本地依赖和凭据诊断

安装到 Codex

方式 A：使用 Codex Skill 安装器

在 Codex 的 Skill 安装器中安装 GitHub 仓库根目录。本仓库根目录本身就是一个 Skill，安装结果应包含 SKILL.md、scripts/、config/ 等目录。

方式 B：手动安装

mkdir -p ~/.codex/skills/baidu-unlimited-ocr
git clone https://github.com/pipiwolve/baidu-unlimited-ocr.git /tmp/baidu-unlimited-ocr
cp -R /tmp/baidu-unlimited-ocr/SKILL.md \
  /tmp/baidu-unlimited-ocr/agents \
  /tmp/baidu-unlimited-ocr/config \
  /tmp/baidu-unlimited-ocr/scripts \
  ~/.codex/skills/baidu-unlimited-ocr/
python3 -m pip install -r ~/.codex/skills/baidu-unlimited-ocr/requirements.txt

Skill 安装器通常会下载并复制整个 GitHub 仓库，这是标准的分发方式；用户不需要逐个配置 Python 文件。运行 Skill 的最小集合是 SKILL.md、agents/、scripts/、config/ 和依赖文件， tests/、README.md、CHANGELOG.md 等主要用于开发、验证和说明。

如果你只想把它作为普通命令行工具安装，也可以在仓库根目录执行：

python3 -m pip install .
baidu-unlimited-ocr --help
baidu-unlimited-ocr-doctor

安装后重新开始一个 Codex 任务，或在下一轮对话中使用：

Use $baidu-unlimited-ocr to识别这个 PDF，并把结果保存到指定目录。

配置鉴权

先阅读凭据获取说明。简要区分如下：

• OCR_API_KEY + OCR_SECRET_KEY：在百度 AI 应用流程中创建 OCR 应用后，从对应产品的“应用列表”获取。这是本 Skill 推荐的方式。
• BCE_API_KEY：已有 bce-v3/ALTAK-... 格式的 BCE API Key 时使用 Bearer Token 方式。
• 千帆控制台：用于千帆大模型服务，不是获取 OCR 应用 Key 的主要入口。

官方入口：OCR 控制台、创建应用说明、OCR API 文档。

推荐使用环境变量，不要把密钥写入仓库、配置文件、命令行参数或聊天记录：

export OCR_API_KEY="你的百度 API Key"
export OCR_SECRET_KEY="你的百度 Secret Key"

也支持 BCE Bearer Token：

export BCE_API_KEY="bce-v3/ALTAK-xxx/xxx"

诊断本地环境：

python3 ~/.codex/skills/baidu-unlimited-ocr/scripts/ocr_doctor.py

未配置凭据时，诊断工具会给出配置提示；也可以直接查看完整指引：

python3 ~/.codex/skills/baidu-unlimited-ocr/scripts/ocr_submit.py --help-auth

若想实际验证 OAuth：

python3 ~/.codex/skills/baidu-unlimited-ocr/scripts/ocr_doctor.py --network

CLI 使用

单文件：

python3 scripts/ocr_pipeline.py \
  --input /absolute/path/report.pdf \
  --output /absolute/path/ocr-output

批量处理：

python3 scripts/ocr_pipeline.py \
  --input /absolute/path/documents \
  --output /absolute/path/ocr-output \
  --concurrent 2 \
  --recursive

公网 URL：

python3 scripts/ocr_pipeline.py \
  --url https://example.com/large.pdf \
  --output /absolute/path/ocr-output

自动化调用：

python3 scripts/ocr_pipeline.py \
  --input /absolute/path/report.pdf \
  --output /absolute/path/ocr-output \
  --json

--json 模式只输出机器可读 JSON；退出码为 0 表示成功，非 0 表示失败。

自定义配置

复制默认配置后按需调整：

cp config/default.yaml /tmp/baidu-ocr.yaml
python3 scripts/ocr_pipeline.py \
  --config /tmp/baidu-ocr.yaml \
  --input /absolute/path/report.pdf \
  --output /absolute/path/ocr-output

可调整 API endpoint、轮询间隔、超时、重试策略、文件上限、并发上限和支持格式。相对的 token_cache_file 会落在：

~/.cache/baidu-unlimited-ocr/

不会修改 Skill 安装目录，也不会污染 Git 工作区。

输出

单文件默认生成：

report.md
report.json

批量模式额外生成：

_batch_summary.json

如果不同子目录存在同名文件，批量模式会自动追加稳定短哈希，避免结果互相覆盖。

开发与测试

python3 -m pip install -r requirements.txt
python3 -m unittest discover -s tests -v
python3 -m py_compile scripts/*.py
python3 scripts/ocr_pipeline.py --help

真实 API 测试需要用户自行配置百度凭据，并会消耗 API 配额；仓库中的单元测试默认使用 mock，不会访问百度接口。

安全边界

• 不在日志中打印 API Key、Secret Key 或 Bearer Token。
• CLI 直接传入密钥仅作为兼容选项，优先使用环境变量。
• token 缓存按 API Key 哈希隔离，并尝试设置为 0600。
• 结果文件可能包含敏感文档内容，请自行设置输出目录权限和生命周期。
• 输入 URL 必须是百度服务器可访问的公网地址；不要上传包含敏感信息的文件到不受信任的 URL。

目录结构

baidu-unlimited-ocr/
├── SKILL.md
├── agents/openai.yaml
├── scripts/
│   ├── ocr_pipeline.py
│   ├── ocr_submit.py
│   ├── ocr_query.py
│   ├── ocr_download.py
│   ├── ocr_config.py
│   └── ocr_doctor.py
├── config/default.yaml
├── references/credentials.md
├── tests/
├── requirements.txt
└── README.md

License

MIT