@haatlabs-core/provider-vision

中文文档
0.18.5发布于 2026/11/14Apache-2.0TypeScriptESM + CJS近 30 天下载 4755

Vision checks and product descriptions on top of @haatlabs-core/ai.

原始使用文档
文档目录9 节
  1. Install
  2. What it does
  3. Options
  4. Errors
  5. Gateway and deadlines
  6. Describing a product
  7. Passing
  8. Fixtures
  9. Testing

@haatlabs-core/provider-vision

Install

pnpm add @haatlabs-core/provider-vision

It leaves one package to your app, so the app holds one copy: zod.

What it does

Vision checks and product descriptions over @haatlabs-core/ai's text provider. createVisionChecker(text) answers whether an image shows a product (assess, with an optional caption) or what an image shows (inspect); build text with createTextProvider({ ..., temperature: 0, reasoningEffort }). createDescriber(text) writes a title, HTML description, SEO title and description and tags, in one of three tones and, when given, a language. Model answers are validated field by field and cleaned of unsafe characters.

Options

assess takes the image (WebP, JPEG or PNG, at most MAX_VISION_IMAGE_BYTES, 4 MiB), the product facts (title, vendor, productType, variantTitle), caption, signal and onUsage; inspect the image, signal and onUsage. describe takes product, tone, language, keywords, signal and onUsage.

Errors

@haatlabs-core/ai's AI_PROVIDER_ERROR (the model away, or an answer of the wrong shape) and the core VALIDATION_FAILED: an image of another type, empty or too large, a tone that is not one of DescribeTone, or a language that is not an ISO 639-1 code (from describe and describePrompt alike). passesVision throws a RangeError for a minMatch outside 0 to 1.

Gateway and deadlines

Unlike the other provider packages, the calls here take no CallContext: they run on the @haatlabs-core/ai text provider, which holds its own endpoint, key and timeout, and not through the gateway. The caller's signal and onUsage are the only per-call options.

Describing a product

const describer = createDescriber(text);
const listing = await describer.describe({
  product: { title: 'Trailblazer', brand: 'Acme' },
  tone: DescribeTone.FRIENDLY, // 'plain' | 'technical' | 'friendly'
  language: 'de', // an ISO 639-1 code; 'en' when left out
  keywords: ['bottle'],
});

describe needs all five fields in the answer and returns them cleaned: the HTML keeps only p, br, ul, ol, li, strong, em, h2, h3 without attributes, and the title, SEO title and SEO description are cut at a word to DESCRIPTION_LIMITS. describePrompt builds the same instructions for a caller with its own fields: extraLines go after the core field lines, and shorten asks again for the fields that came back too long. A language that is not one of ISO_639_1_CODES (lower case, so de, not DE), or a tone that is not one of the three, is a VALIDATION_FAILED. beforeTone and afterSeo put a caller's lines before the tone line and after the SEO description line.

Passing

passesVision(assessment, { minMatch }) is true when sameProduct is at least minMatch (default DEFAULT_MIN_MATCH, 0.7; a number from 0 to 1, else RangeError), both watermarkLikelihood and textOverlayLikelihood are known and below MAX_ARTIFACT_LIKELIHOOD (0.5), and suspectedInstructions is false. A null likelihood does not pass. It takes an inspection too: with no sameProduct (or a null one) that check is skipped and only the rest is checked.

Fixtures

@haatlabs-core/provider-vision/fixtures: visionFixtures.assess (with a caption, and passing), .inspect and .describe, the JSON a model replies with, for a fake text provider or a chat completion's content. Written in the shape the prompts ask for, not recorded from a model; each read is a fresh copy.

Testing

pnpm --filter @haatlabs-core/provider-vision test: unit tests against a fake fetch under the real OpenAICompatibleTextProvider.

版本与发布记录

@haatlabs-core/provider-vision 共发布 27 个版本,首次发布于 2026/10/23;过去 12 个月发布了 27 个版本。

版本发布日期距今
0.18.5latest2026/11/143 天前
0.18.42026/11/134 天前
0.18.32026/11/134 天前
0.18.22026/11/134 天前
0.18.12026/11/134 天前
0.18.02026/11/134 天前

关于 @haatlabs-core/provider-vision 的常见问题

@haatlabs-core/provider-vision 是什么?

Vision checks and product descriptions on top of @haatlabs-core/ai.

如何安装 @haatlabs-core/provider-vision?

在项目目录运行 npm install @haatlabs-core/provider-vision,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^4.6.5)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@haatlabs-core/provider-vision 支持 TypeScript 吗?

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

@haatlabs-core/provider-vision 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@haatlabs-core/provider-vision 需要什么版本的 Node.js?

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

@haatlabs-core/provider-vision 可以商用吗?

@haatlabs-core/provider-vision 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@haatlabs-core/provider-vision 的下载量有多少?

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

@haatlabs-core/provider-vision 还在维护吗?

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