92 lines
2.9 KiB
Markdown
92 lines
2.9 KiB
Markdown
# 重量 OCR 接入说明
|
||
|
||
## 功能位置
|
||
|
||
重量 OCR 已作为功能模块并入 `integration-service`，不再作为独立微服务部署，不新增端口、数据库或注册服务名。
|
||
|
||
主要代码：
|
||
|
||
- `controller/WeightOcrController.java`：内部批量识别接口。
|
||
- `service/ocr/WeightOcrBatchService.java`：批次编排、结果汇总和文件落盘。
|
||
- `service/ocr/ImageCropper.java`：图片下方中央区域裁剪。
|
||
- `service/ocr/WeightCandidateSelector.java`：重量候选筛选。
|
||
- `service/ocr/WeightOcrStoragePolicy.java`：输入、输出目录边界保护。
|
||
- `provider/ocr/BaiduMeterClient.java`：百度令牌缓存、识别、限速和重试。
|
||
|
||
## 接口
|
||
|
||
```text
|
||
POST /internal/integrations/weight-ocr/batches
|
||
X-Internal-Service-Token: 内部服务令牌
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"inputDirectory": "batch-001",
|
||
"outputDirectory": null,
|
||
"cropStartRatio": 0.5,
|
||
"horizontalTrimRatio": 0.25,
|
||
"recursive": false
|
||
}
|
||
```
|
||
|
||
`inputDirectory` 默认相对于 `WEIGHT_OCR_INPUT_ROOT`，`outputDirectory` 默认在 `WEIGHT_OCR_OUTPUT_ROOT` 下按批次 ID 自动创建。接口拒绝访问两个受控根目录之外的路径。
|
||
|
||
## 必需配置
|
||
|
||
```text
|
||
BAIDU_OCR_ENABLED=true
|
||
BAIDU_OCR_API_KEY=百度应用的API Key
|
||
BAIDU_OCR_SECRET_KEY=百度应用的Secret Key
|
||
INTERNAL_SERVICE_TOKEN=至少32字节的内部令牌
|
||
```
|
||
|
||
本地默认目录：
|
||
|
||
```text
|
||
${java.io.tmpdir}/baiyue-weight-ocr/input
|
||
${java.io.tmpdir}/baiyue-weight-ocr/output
|
||
```
|
||
|
||
国内服务器默认目录：
|
||
|
||
```text
|
||
/data/baiyue/weight-ocr/input
|
||
/data/baiyue/weight-ocr/output
|
||
```
|
||
|
||
可选配置：
|
||
|
||
| 环境变量 | 默认值 | 说明 |
|
||
| --- | ---: | --- |
|
||
| `WEIGHT_OCR_MAX_IMAGE_SIZE` | `3MB` | 单张原图及裁剪图上限 |
|
||
| `WEIGHT_OCR_MAX_IMAGE_PIXELS` | `40000000` | 解码后最大像素数 |
|
||
| `WEIGHT_OCR_MAX_BATCH_SIZE` | `50` | 单批图片上限 |
|
||
| `BAIDU_OCR_CONNECT_TIMEOUT` | `10s` | 建连超时 |
|
||
| `BAIDU_OCR_REQUEST_TIMEOUT` | `60s` | 单次请求超时 |
|
||
| `BAIDU_OCR_MIN_REQUEST_INTERVAL` | `600ms` | 百度请求最小间隔 |
|
||
| `BAIDU_OCR_MAX_QPS_RETRIES` | `3` | 百度 QPS 限制重试次数 |
|
||
|
||
## 输出文件
|
||
|
||
```text
|
||
批次输出目录/
|
||
├─ batch-results.json
|
||
├─ cropped/
|
||
└─ raw/
|
||
```
|
||
|
||
接口和结果文件仅返回相对于受控根目录的路径，不返回服务器绝对路径。真实百度响应不写入日志，只保存在批次的 `raw` 目录。
|
||
|
||
## 安全边界
|
||
|
||
- 接口仅供内部服务调用，必须校验 `X-Internal-Service-Token`。
|
||
- 百度能力默认关闭，密钥只从环境变量或配置中心密文注入。
|
||
- 同一实例一次只执行一个 OCR 批次，避免并发压垮第三方接口。
|
||
- 单批顺序调用百度接口，并对 QPS 错误执行有上限的退避重试。
|
||
- 支持 `jpg`、`jpeg`、`png`、`bmp`，同时限制文件大小和解码像素数。
|
||
- 当前不访问业务数据库，识别结果由调用方按自己的业务边界处理。
|