id-ocr

本地身份证 OCR 识别工具，基于 PaddleOCR PP-OCRv4 ONNX 模型，无需 GPU，纯 CPU 推理。

功能特性

• 本地离线识别：基于 ONNX Runtime，无需联网即可完成 OCR
• 多策略共识识别：3 种预处理策略投票，提高识别准确率
• LLM 兜底修正：可选接入 Ollama，对低置信度结果进行 LLM 裁定
• 批量处理：支持目录批量扫描，输出 JSON / CSV / Table 格式
• npm 一键安装：npm install -g id-ocr 即可使用

安装

前置条件

• Node.js >= 20
• （可选）Ollama + 本地模型，用于 LLM 兜底

从 npm 安装

# 配置私有 registry（如需要）
npm config set registry https://your-registry.com/

# 全局安装
npm install -g id-ocr

安装过程自动完成：依赖安装 → TypeScript 编译 → ONNX 模型下载。

从源码开发

git clone <repo-url> id-ocr
cd id-ocr
npm install        # 自动编译 + 下载模型

使用方法

单张识别

id-ocr --file 身份证正面.jpg --format json

批量识别

id-ocr --dir ./images --output ./output --format csv

启用共识识别（3 策略投票）

id-ocr --file 身份证正面.jpg --consensus --format json

启用 LLM 兜底

需先部署 Ollama 并在项目根目录配置 llm.config.json：

{
  "baseUrl": "http://localhost:11434"
}

id-ocr --file 身份证正面.jpg --llm qwen2.5:3b --format json

命令行参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --file <path> | 单张图片路径 | - | | --dir <path> | 图片目录（批量） | - | | --output <dir> | 输出目录 | ./output | | --format <fmt> | 输出格式：json / csv / table | table | | --models <dir> | 模型目录 | 内置 models/ | | --consensus | 启用多策略共识识别 | 关闭 | | --llm <model> | 启用 LLM 兜底，指定 Ollama 模型名 | 关闭 |

输出示例

JSON 格式：

{
  "code": 0,
  "message": "success",
  "results": [
    {
      "file": "邵晓秋.jpg",
      "name": "邵晓秋",
      "gender": "女",
      "ethnicity": "汉",
      "birthDate": "19850315",
      "address": "浙江省杭州市...",
      "idNumber": "330102198503150028"
    }
  ]
}

项目结构

id-ocr/
├── src/
│   ├── index.ts                 # CLI 入口
│   ├── scanner.ts               # 图片扫描
│   ├── ocr/
│   │   ├── pipeline.ts          # OCR 主流程
│   │   ├── detector.ts          # 文字检测
│   │   ├── classifier.ts        # 方向分类
│   │   ├── recognizer.ts        # 文字识别
│   │   ├── preProcess.ts        # 图像预处理
│   │   ├── postProcess.ts       # 结果后处理
│   │   └── strategyConfig.ts    # 多策略配置
│   ├── extractor/
│   │   ├── idCardExtractor.ts   # 身份证字段提取
│   │   └── validators.ts        # 字段校验
│   ├── consensus/
│   │   ├── consensusEngine.ts   # 共识投票引擎
│   │   ├── consensusPipeline.ts # 共识流程
│   │   └── consensusTypes.ts    # 类型定义
│   ├── llm/
│   │   ├── llmConfig.ts         # LLM 配置解析
│   │   └── llmResolver.ts       # LLM 修正逻辑
│   ├── output/
│   │   ├── formatter.ts         # 输出格式化
│   │   └── responseBuilder.ts   # 响应构建
│   └── utils/
│       └── logger.ts            # 日志工具
├── scripts/
│   ├── download-models.ts       # 模型下载脚本（源码）
│   └── postinstall.js           # npm postinstall 钩子
├── tsconfig.json                # TypeScript 配置（主）
├── tsconfig.scripts.json        # TypeScript 配置（scripts）
└── package.json

发布

# 配置 registry（首次）
echo "//your-registry.com/:_authToken=YOUR_TOKEN" >> .npmrc
echo "registry=https://your-registry.com/" >> .npmrc

# 发布（prepublishOnly 自动编译）
npm publish

许可证

MIT