ocr-llm-sdk

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后，任务会返回结果，但是可能任务并没有完成）