@happyvertical/ocr

中文文档
0.62.1发布于 2026/10/16MITTypeScriptES Module近 30 天下载 7943

支持Testeract.js、ONNX(PaddleOCR)、HappyVertical AI-后置视觉 OCR和无限制-OCR的节点第一OCR接口

中文使用文档
文档目录22 节
  1. 编号: ocr 标题:“@happyvertical/ocr:光学字符识别” 侧边栏 标签: "@happyverti…
  2. 概览
  3. 特征
  4. 安装
  5. 快速启动
  6. 供应商
  7. ONNX 提供商(节点.js)
  8. 提供方(节点.js)
  9. LLM OCR 提供者(节点.js)
  10. 无限制- OCR 提供者( 节点, 已服役的 GPU 模型)
  11. PaddleOCR-VL 提供者( 节点, 服务版式解析)
  12. 高级使用
  13. 多语种 OCR
  14. 环境配置
  15. 自定义工厂配置
  16. 处理错误
  17. 写入自定义提供者
  18. 注册自定义提供者
  19. 执行准则
  20. 发展
  21. API 参考
  22. 许可证

编号: ocr 标题:“@happyvertical/ocr:光学字符识别” 侧边栏 标签: "@happyvertical/ocr" 侧边栏( p): 7

@happyvertical/ocr (欢快的垂直)

License: MIT

节点-第一个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配置保持其请求形状:

vllmsglang (默认)
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 成功并不意味着模型被装入.
设置环境变量( 第一个发现胜出)默认
baseUrlHAVE_OCR_PADDLEOCR_URL, (中文(简体) ), HAVE_PDF_PADDLEOCR_URL无( 无法提供)
apiKeyHAVE_OCR_PADDLEOCR_API_KEY, (中文(简体) ), HAVE_PDF_PADDLEOCR_API_KEY无
timeoutHAVE_OCR_PADDLEOCR_TIMEOUT3900000 (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);

执行准则

执行自定义提供者时:

  1. 优雅地处理依赖关系: 期间不扔出 checkDependencies() - 回来 { available: false } 换成
  2. 支持多种图像格式: 处理缓冲器, Uint8Array, 字符串( base64), 和原始 RGB 数据
  3. 提供有意义的错误信息: 使用已打出的错误类( OCRDdependencyError, OCRProcessingError, OCRUN支持的Error)
  4. 实施清理方法:妥善处置资源(工人、实例、缓存)
  5. 验证图像格式: 处理前检查文件签名
  6. 计算信心分数:提供有意义的信心分数(0-100)
  7. 返回边框: 可用时包含精确的文本定位
  8. 地图语言代码: 支持通用语言代码格式

发展

使用寿命周期保护的牵引请求通过管理的合并队列合并,所以 合成合并修正在达到之前重新验证 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/ 没有 最新进展.

许可证

麻省理工学院

版本与发布记录

@happyvertical/ocr 共发布 14 个版本,首次发布于 2026/06/24;过去 12 个月发布了 14 个版本。

版本发布日期距今
0.62.1latest2026/10/161 个月前
0.62.02026/10/161 个月前
0.61.72026/10/141 个月前
0.61.62026/08/222 个月前
0.61.52026/08/133 个月前
0.61.42026/08/013 个月前

关于 @happyvertical/ocr 的常见问题

@happyvertical/ocr 是什么?

支持Testeract.js、ONNX(PaddleOCR)、HappyVertical AI-后置视觉 OCR和无限制-OCR的节点第一OCR接口

如何安装 @happyvertical/ocr?

在项目目录运行 npm install @happyvertical/ocr,或使用 pnpm add / yarn add / bun add。

@happyvertical/ocr 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/ocr 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/ocr 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@happyvertical/ocr 可以商用吗?

@happyvertical/ocr 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/ocr 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/ocr 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,943 次,日均约 265 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/ocr 还在维护吗?

最新版本 0.62.1 发布于 2026/10/16(1 个月前);至今共发布 14 个版本,其中过去 12 个月发布了 14 个;首次发布于 2026/06/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。