OcrLlmSDK 使用文档

📌 简介

• OcrLlmSDK 是一个基于轮询机制的 OCR + LLM 异步任务管理 SDK，提供任务创建、结果获取、状态监听等功能，支持 图片 URL、Base64、二进制文件 方式发起任务，并可自动轮询更新任务状态与结果。

• 也可以直接使用同步方法createByUrl(imageUrl,prompt)、createByBase64(base64Str,prompt)、createByBinary(file,prompt)，直接获取识别结果,参数与创建任务一致（等待时间较长）。

📦 安装

npm install ocr-llm-sdk
# 或
yarn add ocr-llm-sdk

本地引用：

import OcrLlmSDK from './OcrLlmSDK';

🛠 初始化

import OcrLlmSDK, { SDKConfig } from 'ocr-llm-sdk';

const sdk = new OcrLlmSDK({
  baseUrl: 'https://api.example.com',
  apiKey: 'your-api-key',
  type: "ocr-llm",
  scenario: "material_label"
} as SDKConfig);

📄 类型定义

所有类型从 ocr-llm-sdk 导出, 概要如下：

| 类型名 | 说明 | |--------|------| | SDKConfig | SDK 初始化配置（API 地址、类型、鉴权信息，场景代码 等），类型支持 ocr 或 ocr-llm | | TaskStatus | 任务状态枚举：pending / processing / completed / failed / not_found | | OcrResult | OCR识别任务结果 | | OcrLlmResult | OCR识别 + LLM提取任务结果 |

类型SDKConfig的字段信息

| 字段名 | 类型 | 说明 | |--------|------|------| | baseUrl | string | OCR+LLM服务的域名/地址 | | apiKey | string | 经过授权的 API-KEY | | type | enum<string> | ocr代表仅OCR识别 或 ocr-llm代表OCR识别+LLM提取 | | scenario | enum<string> | 场景代码: material_label代表药物标签识别场景 |

类型OcrResult 的字段信息

| 字段名 | 类型 | 说明 | |--------|------|------| | task_id | string | 任务ID | | scenario | string | 场景代码 | | texts | string[] | OCR 从图片中识别的文字列表 | | img_ms | number | 图片优化的耗时(ms) | | ocr_ms | number | OCR 识别的耗时(ms) | | status | enum<TaskStatus> | 任务状态，pending / processing / completed / failed / not_found | | error | string | 错误信息，无错误时为空 '' |

响应实例

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "task_id": "e81a58a1-3c8f-4a82-9dd5-d9330921f714",
        "scenario": "material_label",
        "texts": [
            "封口签",
            "YH001胶囊/安慰剂",
            "方案编号：YH001AA-1101",
            "药物编号：D0987",
            "药物提供方：杭州禹泓医药科技有限公司"
        ],
        "img_ms": 111,
        "ocr_ms": 0,
        "status": "completed",
        "error": ""
    },
    "success": true,
    "time": "2025-08-20T18:20:06.104419"
}

类型OcrLlmResult 的字段信息

| 字段名 | 类型 | 说明 | |--------|------|------| | task_id | string | 任务ID | | scenario | string | 场景代码 | | texts | string[] | OCR 从图片中识别的文字列表 | | data | any[] | 大模型提取出的对象（数据）列表，对象结构可以通过LLM的提示词定义出来 | | img_ms | number | 图片优化的耗时(ms) | | ocr_ms | number | OCR 识别的耗时(ms) | | llm_ms | number | 大模型提取的耗时(ms) | | status | enum<TaskStatus> | 任务状态，pending / processing / completed / failed / not_found | | error | string | 错误信息，无错误时为空 '' |

响应实例

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "task_id": "4d9ee0d0-f961-4880-b06f-e57677a2905f",
        "scenario": "material_label",
        "texts": [
            "封口签",
            "YH001胶囊/安慰剂",
            "方案编号：YH001AA-1101",
            "药物编号：D0987",
            "药物提供方：杭州禹泓医药科技有限公司"
        ],
        "img_ms": 126,
        "ocr_ms": 0,
        "status": "completed",
        "error": "",
        "data": [
            {
                "protocol_no": "YH001AA-1101",
                "kit_no": "D0987",
                "sponsor": "杭州禹泓医药科技有限公司"
            }
        ],
        "llm_ms": 1679
    },
    "success": true,
    "time": "2025-08-20T18:45:48.188575"
}

🚀 API 文档

任务创建

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | createTaskByUrl(imageUrl,prompt) | string 图片 URL，prompt 为用户提示词 | Promise<{task_id: string}> | 通过图片 URL 创建任务 | | createTaskByBase64(base64Str,prompt) | string Base64 字符串，prompt 为用户提示词 | Promise<{task_id: string}> | 通过 Base64 字符串创建任务 | | createTaskByBinary(file,prompt) | File 文件对象，prompt 为用户提示词 | Promise<{task_id: string}> | 通过二进制文件创建任务 |

💡 创建成功（code === 200）时，如果轮询已启动，会自动将任务加入监听列表。

任务结果

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | getResult(taskId) | string 任务 ID | Promise<OcrResult \| OcrLlmResult> | 获取任务最新状态与结果 |

轮询监听

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | startListening(intervalMs?) | number（毫秒，可选，默认 1000） | void | 启动任务状态轮询 | | stopListening() | 无 | void | 停止任务轮询并清空任务列表 |

任务管理

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | appendTask(taskId) | string 任务 ID | void | 手动将任务加入监听列表 | | getTaskList() | 无 | {task_id: "task status"}[] | 获取任务列表（任务 ID + 状态） | | getTaskResultList() | 无 | OcrResult[] \| OcrLlmResult[] | 获取任务结果列表 |

回调注册

| 方法 | 参数 | 返回值 | 说明 | |------|------|--------|------| | onProcessing(callback) | (tasks: {task_id: "task status"}[], results： OcrResult[] \| OcrLlmResult[]) => void | void | 注册轮询回调，任务状态或结果更新时触发 |

💡 使用示例

import OcrLlmSDK from 'ocr-llm-sdk';

const sdk = new OcrLlmSDK({
  baseUrl: 'https://api.example.com',
  apiKey: 'test-key',
  type: "ocr-llm",
  scenario: "material_label"
});

sdk.onProcessing((tasks, results) => {
  console.log('任务状态更新:', tasks);
  console.log('任务结果更新:', results);
});

(async () => {
  // 启动监听（每秒轮询一次）
  sdk.startListening(1000);

  // 创建任务
  const res = await sdk.createTaskByUrl('https://example.com/test.jpg', "用户提示词【可选】");
  console.log('任务创建返回:', res);

  // 30 秒后停止监听
  setTimeout(() => {
    sdk.stopListening();
  }, 30000);
})();

⚠ 注意事项

1. 轮询机制：
   • 任务必须先加入 taskList 才会被轮询更新状态（通过任务创建自动加入，或手动 appendTask）。
2. 任务完成后：
   • SDK 不会自动移除完成或失败的任务，需要业务端根据需求处理。
3. 回调触发频率：
   • onProcessing 回调会在每次轮询时触发，即使任务状态无变化。
4. 防止重复：
   • appendTask 会检测任务 ID 是否已存在，避免重复监听。
5. 同步方法时限：
   • createByXXX() 需要等待接口响应的时间较长（最长60S后，任务会返回结果，但是可能任务并没有完成）