编号: ocr 标题:“@happyvertical/ocr:光学字符识别” 侧边栏 标签: "@happyvertical/ocr" 侧边栏( p): 7
@happyvertical/ocr (欢快的垂直)
节点-第一个OCR接口,用于服务器侧文本提取的多提供者支持. HAD SDK生态系统的一部分.
概览
这个 @happyvertical/ocr 软件包为光学字符识别(OCR)操作提供统一的Node.js接口,提供提供者选择和倒置支持. 它将不同OCR引擎的复杂性加以分解,同时将包入点保持为服务器侧使用优化.
特征
- 多服务支持: United API for Tesceract.js,基于ONNX的OCR引擎(PaddleOCR PP-OCRv4),HappyVertical AI-后置视觉 OCR,服务于无限-OCR端点,服务于PaddleOCR-VL布局解析
- 智能倒计时: 主供应商失败时自动选择和倒置
- 节点- 第一运行时间: 优化Node.js软件包和服务器侧工作流程
- 环境检测: 根据运行时环境选择兼容的 OCR 提供者
- 业绩优化:懒散地装载OCR依赖性和高效率的供应商管理
- 多语言支持: 60+ 有宇宙魔方语言, 7个核心语言 有ONNX语言
- 取出边框: 文字级别和行级文字定位
- 信心分数: 逐一检测和总体信心分数(0-100)
- 格式支持: PNG, JPEG, BMP, TIFF, 原始 RGB 数据, 基数64 字符串, 并服务视觉模型 OCR
安装
# npm
npm install @happyvertical/ocr
# pnpm
pnpm add @happyvertical/ocr
# yarn
yarn add @happyvertical/ocr
# bun
bun add @happyvertical/ocr
该软件包默认包括了Testeract.js,一个PaddleOCR ONNX供应商,拥有软件包拥有的Sharp 0.35和ONNX运行时依赖性,LLM支持的OCR通过 @happyvertical/ai,以及当您与 vLLM 或 SGLang, 直接或背后 Bifrost 服务时, Baidu Unlimited- OCR 的节点提供者。 继续从 @gutenye/ocr-models; 此寄存器中没有模式二进制 。 提供商发现时不装入Sharp或ONNX Runtime本地加通. 依赖性检查在孤立的子程序中验证了附加物, 并且 ONNX 提供者只通过服务器加载它们 @happyvertical/ocr/node 当它进行第一次OCR操作时边界。 这使得浏览器和SSR从翻转本土依赖性中构建起来,同时在同样使用本地文档或图像库如克罗伊兹贝格和夏普的进程中保持发现和依赖性检查的安全.
快速启动
import { getOCR } from '@happyvertical/ocr';
// Get OCR factory with automatic provider selection
const ocrFactory = getOCR();
// Check if OCR is available
const available = await ocrFactory.isOCRAvailable();
if (available) {
// Perform OCR on images
const result = await ocrFactory.performOCR([
{ data: imageBuffer, format: 'png' }
], {
language: 'eng',
confidenceThreshold: 70
});
console.log('Extracted text:', result.text);
console.log('Confidence:', result.confidence);
console.log('Processing time:', result.metadata?.processingTime);
}
供应商
ONNX 提供商(节点.js)
高精度OCR使用PaddleOCR PP-OCRv4型号并带有ONNX运行时. 提供印刷和手写文本的优异性能.
特征 :
- 最高准确度(90分)
- 精确的边框检测
- 自动图像格式转换
- 7个核心语言:英文、中文(简化/传统)、日文、韩文、法文、德文
示例
import { getOCR } from '@happyvertical/ocr';
const onnxFactory = getOCR({ provider: 'onnx' });
const result = await onnxFactory.performOCR(images, {
language: 'eng',
confidenceThreshold: 85
});
// Access bounding box information
result.detections?.forEach((detection) => {
console.log(`Text: "${detection.text}"`);
console.log(`Confidence: ${detection.confidence.toFixed(1)}%`);
if (detection.boundingBox) {
const bbox = detection.boundingBox;
console.log(`Position: (${bbox.x}, ${bbox.y})`);
console.log(`Size: ${bbox.width}x${bbox.height}`);
}
});
提供方(节点.js)
节点.js OCR使用魔方.js,语言支持范围很广. 机器打印文本精度良好.
特征 :
- 60+ 自动模式下载语言
- 单词级信任分数和边框
- 零系统依赖性
- 在没有系统 OCR 依赖的 Node.js 工作
示例
import { getOCR } from '@happyvertical/ocr';
const tesseractFactory = getOCR({ provider: 'tesseract' });
const result = await tesseractFactory.performOCR(images, {
language: 'eng+chi_sim+jpn', // Multi-language support
confidenceThreshold: 70
});
console.log('Text extracted:', result.text);
console.log('Languages used:', result.metadata?.language);
LLM OCR 提供者(节点.js)
视觉模型 OCR 用途 @happyvertical/ai 对于基本的AI客户端,所以OCR调用者不会直接即时化模型SDK.
特征 :
- 与HappyVertical AI兼容的视觉模型合作
- 支持 API- key 或 OAuth2- 备份端点
- 可返回纯文本或结构化文本部分
示例
import { LiteLLMProvider } from '@happyvertical/ocr';
const provider = new LiteLLMProvider({
baseUrl: 'https://litellm.example.com/v1',
apiKey: process.env.HAVE_OCR_LITELLM_API_KEY,
model: 'gpt-4o',
outputMode: 'structured'
});
const result = await provider.performOCR(images, {
language: 'eng'
});
console.log('LLM OCR completed:', result.text);
无限制- OCR 提供者( 节点, 已服役的 GPU 模型)
这个 unlimited-ocr 供应商对运行的谈话 baidu/ 无限制- OCR 服务器通过 OpenAI 兼容的聊天完成端点。 服务器可以是vLLM或SGLang,端点可以是直接的,也可以通过HappyVertical Bifrost进行路由.
两个服务器期望不同的请求字段,因此设置后端以匹配服务器(backend 在配置中,或 HAVE_OCR_UNLIMITED_BACKEND) (中文(简体) ). 默认是 sglang,因此现有的SGLang配置保持其请求形状:
vllm | sglang (默认) | |
|---|---|---|
| N- gram 日志处理器参数 | vllm_xargs: { ngram_size, window_size } | custom_params: { ngram_size, window_size } |
| 提示 | 一个 <image> 每个发送的图像,然后提示: <image>document parsing., (中文(简体) ), <image><image>Multi page parsing. 2页(见下文) | document parsing. 编号 : Multi page parsing. |
| 图像模式 | 由服务器选择 | images_config.image_mode (单位:千美元)HAVE_OCR_UNLIMITED_IMAGE_MODE(中文(简体) ) |
custom_logit_processor | 未发送( 处理器已启用服务器侧) | 配置时发送 |
两个后端都发送 skip_special_tokens: false,将文本部分置于图像部分之前,并使用一个128的n克窗口用于一个图像,1024的多图像/多页请求(HAVE_OCR_UNLIMITED_SINGLE_IMAGE_NGRAM_WINDOW, (中文(简体) ), HAVE_OCR_UNLIMITED_MULTI_IMAGE_NGRAM_WINDOW,或 HAVE_OCR_UNLIMITED_NGRAM_WINDOW 对所有请求; HAVE_OCR_UNLIMITED_NGRAM_SIZE 默认为35)。 vLLM 拒绝其请求 <image> 占位符计数与其图像计数不同,所以 vllm 后端一个已配置的提示 (p)HAVE_OCR_UNLIMITED_PROMPT, (中文(简体) ), HAVE_OCR_UNLIMITED_MULTI_PAGE_PROMPT)已经保持了完全一个 <image> 每个图像发送不变;否则 <image> 符号被移除,每个图像有一个被前缀。 vLLM忽略了它不知道的请求字段,所以一个vLLM服务器发送了SGLang形状运行时没有n-gm的参数,而长文件可以在坐标符上循环.
何时 transport 未明确设置, 提供者继续使用 direct 提供无限- OCR 基础 URL 时 (baseUrl 或者说 HAVE_OCR_UNLIMITED_BASE_URL; Bifrost 仅在没有配置直接端点时从 Bifrost 环境变量中推断出.
此提供者不会在Node.js内装入Python/CUDA模型. 您还需要运行 GPU 接入的模型服务器 .
直接 vLLM 结束点 :
export HAVE_OCR_PROVIDER=unlimited-ocr
export HAVE_OCR_UNLIMITED_TRANSPORT=direct
export HAVE_OCR_UNLIMITED_BACKEND=vllm
export HAVE_OCR_UNLIMITED_BASE_URL=http://127.0.0.1:8000
export HAVE_OCR_UNLIMITED_MODEL=Unlimited-OCR
直接SGLang终点 :
export HAVE_OCR_PROVIDER=unlimited-ocr
export HAVE_OCR_UNLIMITED_TRANSPORT=direct
export HAVE_OCR_UNLIMITED_BACKEND=sglang
export HAVE_OCR_UNLIMITED_BASE_URL=http://127.0.0.1:10000
export HAVE_OCR_UNLIMITED_MODEL=Unlimited-OCR
import { getOCR } from '@happyvertical/ocr';
const ocr = getOCR({ provider: 'unlimited-ocr' });
const result = await ocr.performOCR([
{ data: imageBuffer, format: 'png' }
]);
console.log(result.text);
Bifrost 路由终点 :
export HAVE_OCR_PROVIDER=unlimited-ocr
export HAVE_OCR_UNLIMITED_TRANSPORT=bifrost
export HAVE_OCR_BIFROST_BASE_URL=https://bifrost.happyvertical.com
export HAVE_OCR_BIFROST_API_KEY=<virtual-key>
export HAVE_OCR_BIFROST_MODEL=Unlimited-OCR
import { getOCR } from '@happyvertical/ocr';
const ocr = getOCR({
provider: 'unlimited-ocr',
fallbackProviders: ['tesseract']
});
const result = await ocr.performOCR([
{ data: imageBuffer, format: 'png' }
]);
程序配置 :
import { getOCR } from '@happyvertical/ocr';
const ocr = getOCR({
provider: 'unlimited-ocr',
providerConfig: {
'unlimited-ocr': {
transport: 'direct',
backend: 'vllm',
baseUrl: 'http://127.0.0.1:8000',
model: 'Unlimited-OCR',
stream: true
}
}
});
用 vLLM 运行模型服务器 :
跟着 vLLM 食谱。服务器需要食谱图像及其n克日志处理器;没有处理器,坐标符上的长文件循环:
docker run --rm --gpus all --network host --ipc host \
vllm/vllm-openai:unlimited-ocr \
baidu/Unlimited-OCR \
--served-model-name Unlimited-OCR \
--trust-remote-code \
--logits_processors vllm.model_executor.models.unlimited_ocr:NGramPerReqLogitsProcessor \
--no-enable-prefix-caching \
--mm-processor-cache-gb 0
与 backend: 'vllm' 提供者发送每个请求 vllm_xargs 这个处理器读取.
用 SGLang 运行模型服务器 :
遵循无限制-OCR的型号卡,以精确的SGLang环境. 所记录的服务器形状是:
python -m sglang.launch_server \
--model baidu/Unlimited-OCR \
--served-model-name Unlimited-OCR \
--attention-backend fa3 \
--page-size 1 \
--mem-fraction-static 0.8 \
--context-length 32768 \
--enable-custom-logit-processor \
--disable-overlap-schedule \
--skip-server-warmup \
--host 0.0.0.0 \
--port 10000
对于最好的长文档输出,无限制-OCR也支持SGLang的 custom_logit_processor。如果您的网关/代理注入,则不需要库配置。 如果客户端必须发送, 设置 HAVE_OCR_UNLIMITED_CUSTOM_LOGIT_PROCESSOR 的数值:
python - <<'PY'
from sglang.srt.sampling.custom_logit_processor import DeepseekOCRNoRepeatNGramLogitProcessor
print(DeepseekOCRNoRepeatNGramLogitProcessor.to_str())
PY
与 sglang 后端, 提供者发送 gundam 一个图像的图像模式 base 默认的多图像/多页请求的图像模式。 覆盖 HAVE_OCR_UNLIMITED_IMAGE_MODE=base 或者说 gundam 需要的时候.
PaddleOCR-VL 提供者( 节点, 服务版式解析)
这个 paddleocr-vl 提供者发送图像到一个 拖放( P) /layout-parsing 服务:全管,有布局检测和VL识别器. @happyvertical/pdf 通过同一服务读取 PDF paddleocr 阅读器提供者),因此图像和PDF可以共享一个模型.
import { getOCR } from '@happyvertical/ocr';
const ocr = getOCR({
provider: 'paddleocr-vl',
providerConfig: {
'paddleocr-vl': { baseUrl: 'http://paddleocr-vl:8080' },
},
});
const { text } = await ocr.performOCR([{ data: scanBytes }]);
- 仅明取出. 图像离开过程,所以
auto从不选择此提供者。 说吧provider: 'paddleocr-vl'或者说HAVE_OCR_PROVIDER=paddleocr-vl) (中文(简体) ). - 每页一个请求. PNG和JPEG在当地进行验证,发送时不变. TIFF、WebP、GIF、BMP和原始像素缓冲器首先被转换为PNG(
bmp-ts解码为BMP;Sharp 编码为PNG),多页的TIFF(典型的扫描器输出)按页面发送,顺序排列. 仅在验证或转换图像时才有尖锐的加载,在发现时从未有过. 每个图像响应必须包含准确的一页,包括一个空白图像有空文本的一页. 在任何请求之前都拒绝未知或不可解密的输入。 远程图像 URL 被拒绝, 从未获取 . - 结果.
text是服务的Markdown,以表格为HTML,并用空白行连接页面.detections每页有一个条目.confidence任何文本都是100,因为服务报告没有得分. - 不得复试. 丢弃的连接可以让 GPU 解析运行 。 错误消息从不包含服务的响应或文档文本.
- 超时. 默认时间为65分钟,涵盖点播后冷起步.
OCROptions.timeout(这样)HAVE_OCR_TIMEOUT)被这个提供商忽略了,因为对本地引擎的限定大小会切断一个冷起步. 设置提供者自己的timeout换句话说. checkDependencies()只检查配置 。 一个代理/health成功并不意味着模型被装入.
| 设置 | 环境变量( 第一个发现胜出) | 默认 |
|---|---|---|
baseUrl | HAVE_OCR_PADDLEOCR_URL, (中文(简体) ), HAVE_PDF_PADDLEOCR_URL | 无( 无法提供) |
apiKey | HAVE_OCR_PADDLEOCR_API_KEY, (中文(简体) ), HAVE_PDF_PADDLEOCR_API_KEY | 无 |
timeout | HAVE_OCR_PADDLEOCR_TIMEOUT | 3900000 (65分钟) |
高级使用
多语种 OCR
import { getOCR } from '@happyvertical/ocr';
const ocrFactory = getOCR();
// Single language
const englishResult = await ocrFactory.performOCR(images, {
language: 'eng'
});
// Multiple languages
const multilingualResult = await ocrFactory.performOCR(images, {
language: 'eng+chi_sim+jpn+kor',
confidenceThreshold: 60
});
// Get supported languages from active provider
const supportedLanguages = await ocrFactory.getSupportedLanguages();
console.log('Supported languages:', supportedLanguages);
环境配置
import { getOCR } from '@happyvertical/ocr';
const ocrFactory = getOCR();
const environment = ocrFactory.getEnvironment();
if (environment !== 'node') {
throw new Error('@happyvertical/ocr is intended for Node.js runtimes');
}
const result = await ocrFactory.performOCR(images, {
language: 'eng',
confidenceThreshold: 85
});
自定义工厂配置
import { OCRFactory } from '@happyvertical/ocr';
const customFactory = new OCRFactory({
provider: 'onnx', // Force specific provider
fallbackProviders: ['tesseract'], // Fallback chain
defaultOptions: {
language: 'eng',
confidenceThreshold: 85
}
});
// Check provider availability and capabilities
const providersInfo = await customFactory.getProvidersInfo();
for (const provider of providersInfo) {
console.log(`Provider: ${provider.name}`);
console.log(`Available: ${provider.available}`);
if (provider.capabilities) {
console.log(`Languages: ${provider.capabilities.supportedLanguages.length}`);
console.log(`Bounding boxes: ${provider.capabilities.hasBoundingBoxes}`);
}
}
// Process images
try {
const result = await customFactory.performOCR(images);
console.log('OCR completed:', result.text);
} finally {
await customFactory.cleanup(); // Important for resource cleanup
}
处理错误
import {
OCRError,
OCRDependencyError,
OCRProcessingError,
OCRUnsupportedError
} from '@happyvertical/ocr';
try {
const result = await ocrFactory.performOCR(images);
console.log('OCR successful:', result.text);
} catch (error) {
if (error instanceof OCRDependencyError) {
console.error('OCR dependencies missing:', error.message);
console.log('Provider:', error.provider);
} else if (error instanceof OCRProcessingError) {
console.error('OCR processing failed:', error.message);
console.log('Provider:', error.provider);
console.log('Context:', error.context);
} else if (error instanceof OCRUnsupportedError) {
console.error('Unsupported operation:', error.message);
console.log('Provider:', error.provider);
} else if (error instanceof OCRError) {
console.error('General OCR error:', error.message);
}
}
写入自定义提供者
您可以通过执行 OCRProvider 接口 :
import {
OCRProvider,
OCRImage,
OCRResult,
OCROptions,
DependencyCheckResult,
OCRCapabilities
} from '@happyvertical/ocr';
export class MyOCRProvider implements OCRProvider {
readonly name = 'my-provider';
async performOCR(images: OCRImage[], options?: OCROptions): Promise<OCRResult> {
// Process images and return OCR results
const text = ''; // Extract text from images
const confidence = 0; // Calculate average confidence
const detections = []; // Optional: word/line detections with bounding boxes
return {
text,
confidence,
detections,
metadata: {
provider: this.name,
processingTime: 0,
language: options?.language || 'eng',
detectionCount: detections.length
}
};
}
async checkDependencies(): Promise<DependencyCheckResult> {
// Check if provider is available
try {
// Verify dependencies are installed and functional
return {
available: true,
details: { version: '1.0.0' }
};
} catch (error: any) {
return {
available: false,
error: error.message,
details: { reason: 'Dependencies not installed' }
};
}
}
async checkCapabilities(): Promise<OCRCapabilities> {
// Return provider capabilities
return {
supportedLanguages: ['eng', 'spa', 'fra'],
supportedFormats: ['png', 'jpeg'],
maxImageSize: 4096,
hasBoundingBoxes: true,
hasConfidenceScores: true
};
}
getSupportedLanguages(): string[] {
return ['eng', 'spa', 'fra'];
}
async cleanup?(): Promise<void> {
// Optional: Clean up resources
// Terminate workers, clear caches, etc.
}
}
注册自定义提供者
import { OCRFactory } from '@happyvertical/ocr';
import { MyOCRProvider } from './my-ocr-provider';
// Create factory with custom provider
const factory = new OCRFactory({
provider: 'my-provider'
});
// Manually register provider
factory.addProvider('my-provider', new MyOCRProvider());
// Use custom provider
const result = await factory.performOCR(images);
执行准则
执行自定义提供者时:
- 优雅地处理依赖关系: 期间不扔出
checkDependencies()- 回来{ available: false }换成 - 支持多种图像格式: 处理缓冲器, Uint8Array, 字符串( base64), 和原始 RGB 数据
- 提供有意义的错误信息: 使用已打出的错误类( OCRDdependencyError, OCRProcessingError, OCRUN支持的Error)
- 实施清理方法:妥善处置资源(工人、实例、缓存)
- 验证图像格式: 处理前检查文件签名
- 计算信心分数:提供有意义的信心分数(0-100)
- 返回边框: 可用时包含精确的文本定位
- 地图语言代码: 支持通用语言代码格式
发展
使用寿命周期保护的牵引请求通过管理的合并队列合并,所以
合成合并修正在达到之前重新验证 main。 。 。 .
地方共同质量检查:
pnpm lint
pnpm typecheck
pnpm build
pnpm deps:check
pnpm docs:api
pnpm docs:api:check
pnpm test:coverage
pnpm pack --dry-run
覆盖范围使用Vitest V8覆盖和大门语句、分支、功能和
线条在 80/65/80/80。 。 。 .
向公众npm登记册公布的版本(registry.npmjs.org通过
Changersets发布工作流程. 工作流程对寄存器的期望 NPM_TOKEN
要配置的密钥.
API 参考
生成的 API 参考文献 docs/api/ 并且从
公共JSDoc与TypeDoc的评论.
pnpm docs:api
pnpm docs:api:check
docs:api:check 重新生成 API 引用, 如果失败 docs/api/ 没有
最新进展.
许可证
麻省理工学院