Viscribe 实战：为 AI Agent 打造图像智能感知层

AI Agent 处理文本的能力已经很强了，但遇到图片就尴尬了——你可以把图片转 Base64 塞进去，但每次都要自己写 prompt 模板、解析输出、处理重试。更麻烦的是，你拿到的是一段自然语言描述，想让下游系统消费还得再解析一遍。

Viscribe 就是来解决这个问题的：一个开源的图像智能感知层，专为 AI Agent 设计。你定义好输出结构，传给图片，它返回结构化的 JSON。就这么简单。

4 个 GitHub stars，MIT 许可证，Python 3.10+ 和 Node.js 20+ 双 SDK 支持。今天带你从头跑一遍。

安装

一行搞定：

pip install viscribe

TypeScript 用户也一样简单：

npm install viscribe

五大图像端点

Viscribe 提供了五个核心图像处理端点，覆盖了 AI Agent 日常处理图片的绝大多数场景：

1. 描述（describe）

生成客观的图像描述，可选标签：

from viscribe.images import describe

result = describe(
    image_path="screenshot.png",
    generate_tags=True,
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-xxx",
        "temperature": 1,
    },
)

print(result.data)

2. 分类（classify）

把图片归入你定义的类别清单，适合内容审核、场景识别等场景：

from viscribe.images import classify

result = classify(
    image_path="screenshot.png",
    classes=["dashboard", "error_message", "empty_state", "loading"],
    multi_label=True,
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-xxx",
    },
)

multi_label=True 允许一张图片同时归入多个类别。

3. 视觉问答（VQA）

对图片提问，获取基于图片内容的答案——Agent 需要”看图理解上下文”时的利器：

from viscribe.images import ask

result = ask(
    image_path="chart.png",
    question="What is the trend of API error rate over the past 7 days?",
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-xxx",
    },
)

4. 结构化提取（extract）

这是最核心的功能。 把图片中的信息按照你定义的 schema 提取为结构化数据：

from viscribe.images import extract

result = extract(
    image_path="invoice.jpg",
    output_schema=[
        {"name": "amount", "type": "number", "description": "Total invoice amount"},
        {"name": "currency", "type": "text", "description": "Currency code"},
        {"name": "line_items", "type": "array_text", "description": "Item descriptions"},
    ],
    model_config={
        "model": "gpt-5-mini",
        "api_key": "sk-xxx",
    },
)

支持四种字段类型：text、number、array_text、array_number。

需要更复杂的嵌套结构？直接上 Pydantic：

from pydantic import BaseModel
from viscribe.images import extract

class Receipt(BaseModel):
    store_name: str
    total: float
    items: list[str]
    tax: float

result = extract(
    image_path="receipt.jpg",
    output_schema=Receipt,
    model_config={"model": "gpt-5-mini", "api_key": "sk-xxx"},
)

5. 比较（compare）

两张图片的相似性和差异对比——适合 UI 对比测试、截图 diff 等场景：

from viscribe.images import compare

result = compare(
    image1_path="before.png",
    image2_path="after.png",
    model_config={"model": "gpt-5-mini", "api_key": "sk-xxx"},
)

异步用法

Python 用户可以通过 adescribe、aextract 等异步版本避免阻塞：

import asyncio
from viscribe.images import adescribe

async def main():
    result = await adescribe(
        image_path="screenshot.png",
        generate_tags=True,
        model_config={"model": "gpt-5-mini", "api_key": "sk-xxx"},
    )
    print(result.data)

asyncio.run(main())

也可以复用同一个异步客户端（记得包在 async 函数中）：

import asyncio
from viscribe import ViscribeAI

async def main():
    client = ViscribeAI(
        model_config={"model": "gpt-5-mini", "api_key": "sk-xxx"}
    )
    result = await client.images.adescribe(image_path="screenshot.png")
    print(result.data)

asyncio.run(main())

TypeScript 本身是异步的，直接用 await 即可。

实际应用场景

• 发票/收据自动录入：Agent 收到用户上传的发票截图，用 extract 提取金额、项目、税率后写入数据库
• 错误截图诊断：Agent 看到报错截图，用 classify 判断是否为已知错误类型，ask 获取错误详情
• UI 测试回归：Agent 自动截取页面变化前后的截图，用 compare 检测差异并生成报告
• 内容审核流水线：Agent 用 classify 过滤违规图片，用 describe 生成审核日志

横向对比

小技巧

• API key 永远走环境变量，别硬编码
• Viscribe 兼容任何 OpenAI 格式的端点，所以可以用 Groq、Together AI、Ollama 等替代提供商跑本地模型
• model_config 在多个调用间一致时，建议用 ViscribeAI() 客户端复用配置，避免重复传参
• 图片支持本地路径和 Base64 两种方式，Base64 适合网络场景

总结

Viscribe 不是什么宏大框架，它解决的是一个具体而普遍的问题：让 AI Agent 能结构化地理解图片。不需要每次都写繁琐的 prompt 模板，不需要自己解析模型输出，不需要实现重试逻辑——5 个端点覆盖了 Agent 日常所需的全部图像处理场景。

如果你正在开发需要处理截图的 AI Agent——无论是自动化测试、文档分析、还是内容审核——Viscribe 值得放进工具箱。4 个 stars 不代表它不实用，有时候小工具解决的是大问题。

链接：GitHub | 文档 | 官网