You need to enable JavaScript to run this app.
导航
边缘智能
  • 文档首页
    • /边缘智能/边缘大模型网关/用户指南/API调用指南/文字识别智能体
文字识别智能体
最近更新时间：2025.01.24 16:07:33首次发布时间：2024.12.17 10:49:10
我的收藏

本文介绍了如何使用大模型网关平台预置的文字识别智能体。

能力介绍

文字识别智能体是大模型网关平台预置的一个智能体。该智能体能够从输入图片中提取文本信息，可根据您的提示词进行全局（图片整体）/局部文本提取。结合了最新的多模态大模型和传统深度学习 OCR 算法技术，该智能体泛用性较强，支持绝大部分场景的文本识别。

对于结构化卡证（如银行卡、身份证、驾驶证、行驶证、火车票、增值税发票、印章）整体信息提取的场景，智能体返回固定输出字段。此外，您也可以使用提示词来自定义输出字段。

使用流程

要使用文字识别智能体，您需要：

  1. 创建一个网关访问密钥，并为该密钥绑定文字识别智能体。相关操作，请参见调用平台预置智能体。
    Image
  2. 获取网关访问密钥的 API key。相关操作，请参见查看密钥（API Key）。
  3. 调用文字识别智能体 API 执行文字提取任务。关于 API 的使用说明，请参见 API 使用方法。

调用预览

使用文字识别智能体前，您可以先通过预览功能体验其能力。预览只需要一个网关访问密钥即可。

注意

预览时产生的模型调用会消耗该密钥的免费资源配额。请确保网关访问密钥有可用的 Tokens 配额。

  1. 登录大模型网关控制台。

  2. 在左侧导航栏，选择 模型配置管理 > 智能体管理。
  3. 在 平台预置智能体 标签页，找到 文字识别智能体，单击 操作 列的 调用预览。
  4. 在 调用预览 面板，参照以下步骤来体验文字识别智能体的能力：
    1. 上传一张要识别的图片。
    2. 选择要使用的 网关访问密钥，然后单击 立即体验。
    3. 在输入框中输入提示词，向智能体下达任务指示。

alt

API 使用方法

注意

文字识别智能体 API 仍在测试，暂不建议您在实际业务环境使用。

说明

文字识别智能体 API 遵循 OpenAI 的 API 格式，可按照 OpenAI 标准请求格式调用。

HTTP 调用

请求方法：POST
Endpoint：https://ai-gateway.vei.volces.com/v1/chat/completions
Curl 请求示例

说明

示例中的YOUR_API_KEY表示网关访问密钥；b64表示输入图片的 base64 编码。生成方式可参考下文 Python 示例。

curl "https://ai-gateway.vei.volces.com/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $YOUR_API_KEY" \
    -d '{
        "model": "AG-ocr-agent",
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "text", 
                        "text": "请帮我提取这张身份证的姓名。"
                    }, 
                    {
                        "type": "image_url", 
                        "image_url": {"url": f"data:image/jpeg;base64,{b64}"}
                    }
                ]
            }
        ],
        "stream": false，
        "max_tokens": 1024,
        "temperature": 0.1
    }'

Python 调用

文字识别智能体遵循 OpenAI 标准格式。当前不支持 stream 输出。要使用智能体，您必须先安装 OpenAI SDK。

安装 OpenAI SDK

pip install openai

Python 请求示例

from openai import OpenAI

api_key = "xxx.xxx"
server_url = "xxxxxx"
client = OpenAI(api_key=api_key, base_url=server_url)

text = {"type": "text", "text": "请帮我提取这张身份证的姓名。"}
#身份证图片的base64编码
b64 = "xxxxx"
image = {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}
messages = [{"role": "user", "content": [text, image]}]

completion = client.chat.completions.create(
    messages=messages,
    model="AG-ocr-agent",
    stream=False,
    temperature=0.7,
    max_tokens=1024
)
print(completion.model_dump_json())

参数说明

  • Model: string（必选）
    模型名称。对于文字识别智能体，该参数取值为 AG-ocr-agent。

  • Messages: array（必选）
    输入信息列表。文字识别智能体不支持多轮对话，因此该参数只包含一条用户的输入信息。
    输入信息格式如下。其中，role=user为固定字段，表示当前是用户输入；content表示输入内容。

    [
    {
        "role": "user", 
        "content": [text, image]
    }
]

    content 包含以下 2 个对象：

    • 文本提示词。格式如下：

      {"type": "text", "text": "请帮我提取这张身份证的姓名。"}

    • 待处理图片的 base64 编码。格式如下：

      {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64}"}}

      格式说明：

      • 支持的的图片格式包括：JPG、JPEG、PNG。
      • 图片的 base64 编码前必须加上类似 data:image/jpeg;base64 的前缀。其中 jpeg 表示输入图片格式是 JPEG；如果格式是 PNG，则要修改成 png。
      • 图片的 base64 编码可通过以下方法生成：
        def img_to_base64(img_path):
    with open(img_path, "rb") as f:
        base64_str = base64.b64encode(f.read()).decode("utf-8")
    return base64_str

    • stream: boolean（可选）
      是否流式输出回复。默认值为 False。目前仅支持 stream=False 的场景。

    • temperature: float（可选）
      采样温度，用于控制模型生成文本的多样性。取值范围： [0, 2)。默认值：0.7。
      数值越高，生成的文本更多样；反之，生成的文本更确定。如果希望每次生成的结果相对稳定，可设置较小的值，如 0.1。

    • max_tokens: int（可选）
      允许模型消费的最大 Token 数，用于需要限制字数（如生成摘要、关键词）、控制成本或减少响应时间的场景。默认值是 2048。

响应结果

{
        "id": "chat-272e76ae32cd4e5394c6f238f7d08dfb",
        "choices": [{
                "finish_reason": "stop",
                "index": 0,
                "logprobs": null,
                "message": {
                        "content": "\n{\n 'name': '边缘智能' \n}\n",
                        "role": "assistant",
                        "refusal": null,
                        "audio": null,
                        "function_call": null,
                        "tool_calls": [],
                        "stop_reason": null
                }
        }],
        "created": 1721044114,
        "model": "AG-ocr-agent",
        "object": "chat.completion",
        "service_tier": null,
        "system_fingerprint": null,
        "usage": {
                "completion_tokens": 36,
                "prompt_tokens": 22,
                "total_tokens": 58,
                "completion_tokens_details": null,
                "prompt_tokens_details": null
        },
        "prompt_logprobs": null
}

在结果中，可重点关注以下字段：

  • Id: string
    本次调用的唯一标识符。
  • choices: array
    模型生成内容的数组，可以包含一个或多个 choice 对象。
    • message: object
      模型输出的消息。
      • content: string
        模型生成的文本。
      • role: string
        智能体的角色，固定为 assistant。
  • Usage: object
    本次调用请求消费的 tokens 信息。
    • completion_tokens: int
      模型生成的回复转换成 tokens 的数量。
    • prompt_tokens: int
      用户的输入转换成 tokens 的数量。
    • total_tokens: int
      prompt_tokens 与 completion_tokens 的总和。

提示词技巧

应用全局/局部提取模式

文本识别智能体提供两种任务处理模式：

  • 全局提取模式
    依赖多模态大模型对输入图片整体进行文字识别，同时以传统 OCR 算法作为支持，提高结构化卡证识别场景的识别精度。

    说明

    支持的结构化卡证包括：银行卡、身份证、驾驶证、行驶证、火车票、增值税发票、印章。

  • 局部提取模式
    只依赖多模态大模型对输入图片上的局部区域进行文字识别。

您可以在 Query 文本中增加特定前缀来指定任务处理模式。支持的前缀如下表所示。

Query 文本前缀说明使用示例

<overall>（默认）

指定使用全局提取模式。
适用于：
结构化卡证的全部信息识别（对于结构化卡证的文本识别结果更可靠）

原始 Query：请帮我提取这张身份证中的所有信息。
带前缀 Query：<overall>请帮我提取这张身份证中的所有信息。

说明

<overall>前缀一般不用专门去加，因为默认使用全局 OCR 模式。

<local>

指定使用局部提取模式。
适用于：

  • 结构化卡证以外的文字识别场景
  • 局部关键信息提取

原始 Query：请帮我提取这张身份证中的姓名信息。
带前缀 Query：<local>请帮我提取这张身份证中的姓名信息。

自定义输出字段

输出结果的字段分为两种类型：

  • 固定输出字段
    对于结构化卡证识别（包括 银行卡、身份证、驾驶证、行驶证、火车票、增值税发票、印章），接口返回的 content 包含针对每种卡证的固定输出字段。具体示例请参见：
  • 自定义输出字段
    您可以在 Query 文本输入中定义期望输出字段与图像中内容字段的映射关系。

    示例：
    假设身份证图片中的姓名信息为 {"姓名"： "张三"}。通过在 Query 文本中指定 请在输出中将字段"姓名"替换成"name"，那么得到的实际输出会是 {"name": "张三"}。

    说明

    在 Query 文本中增加输出字段映射关系的提示时，建议加上 <local> 前缀，以此来降低任务处理时延。因为字段映射是由多模态大模式处理的。

自定义输出字段示例

以下包含 2 个使用自定义输出字段的示例：
示例一
输入图片如下。
Image
使用不同输入文本（Query）获得的输出结果如下。

输入文本

输出结果

请帮我提取这张图片中的文本信息，请用JSON的格式进行输出。

{
 "url": "https://www.volcengine.com/",
 "公司名称": "北京火山引擎科技有限公司",
 "业务咨询": "service@volcengine.com",
 "电话": "400-850-0030",
 "工作时间": "(周一至周五 10:00-18:00)"
}

请帮我提取这张图片中的文本信息，请用JSON的格式进行输出，并按以下规则进行字段映射，第一行的字段为url，第二行的字段为name， 第三行的字段为service， 第四行的字段为phone， 第四行括号中的内容字段为worktime。

{
 "url": "https://www.volcengine.com/",
 "name": "北京火山引擎科技有限公司",
 "service": "service@volcengine.com",
 "phone": "400-850-0030",
 "worktime": "(周一至周五 10:00-18:00)"
}

示例二
输入图片如下。
Image
使用不同输入文本（Query）获得的输出结果如下。

输入文本

输出结果

请帮我提取这张身份证上的全部信息，并以JSON的格式进行输出。

{
 "姓名": "侯小珂",
 "性别": "女",
 "民族": "汉",
 "出生日期": "1999年5月7日",
 "住址": "北京市海淀区知春路1号2栋3号",
 "公民身份号码": "110129199905070025"
}

请帮我提取这张身份证上的全部信息，并以JSON的格式进行输出，请遵循如下格式进行字段映射，将姓名替换成name, 将性别替换成gender， 将民族替换成ethnicity，将出生替换成birth_of_date，将住址替换成address，将公民身份号码替换成id_code。

{
 "name": "侯小珂",
 "gender": "女",
 "ethnicity": "汉",
 "birth_of_date": "1999 年 5 月 7 日",
 "address": "北京市海淀区知春路1号 2栋3号",
 "id_code": "110129199905070025"
}

Python 代码示例

以下是一段完整的 Python 代码示例。

from openai import OpenAI
import base64
from io import BytesIO
from PIL import Image, ImageOps

def img_to_base64(img_path):
    with open(img_path, "rb") as f:
        base64_str = base64.b64encode(f.read()).decode("utf-8")
    return base64_str


api_key = "xxx.xxx"
server_url = "https://ai-gateway.vei.volces.com/v1"
client = OpenAI(api_key=api_key, base_url=server_url)

# 输入图片
image_file = 'id-card.jpg'
# 输入文本
query = "<local>请帮我提取这张身份证上的全部信息，并以JSON的格式进行输出，请遵循如下格式进行字段映射，将姓名替换成name, 将性别替换成gender， 将民族替换成ethnicity，将出生替换成birth_of_date，将住址替换成address，将公民身份号码替换成id_code。"

with open(image_file, "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

messages = [
  {
    "role": "user", 
    "content": [
        {"type": "text", "text": query}, 
        {"type": "image_url","image_url": {"url": f"data:image/jpeg;base64,{b64}"}
     ]
  }
]
   
completion = client.chat.completions.create(
    messages=messages,
    model="AG-ocr-agent",
    stream=False,
    temperature=0.2,
    max_tokens=1024
)
  
result = completion.choices[0].message.content
print(result)

FAQ

文字识别智能体支持的输入类型有哪些？

支持输入图片和文本。

  • 图片输入
    • 支持的图片格式包括：JPEG、JPG、PNG。
    • 图片必须转换成 base64 编码，添加 base64 前缀data:image/jpeg;base64。具体转换方法可参见前文描述。
  • 文本输入
    无限制。正常情况下就直接输入 Query 文本即可。如果是局部信息提取，或者特殊场景下的文本提取，可以在 Query 前面添加<local>来提升执行效率。

文字识别智能体如何得到期望的结构化输出？

  • 对于常见的结构化卡证识别，智能体内置了结构化输出模板。详情可参考上文。
  • 对于其他文档或者图片中不包含 KEY 的输入，需要在输入 Query 中通过文本来描述自己想要的结果，对相关内容进行 KEY的定义或者映射。这样可以得到自己想要的结构化输出结果。

如何保证智能体针对同一个输入每次返回相同的结果？

由于 beam search 的原因，大模型生成的结果具有一定随机性。如果想要同一个输入每次生成的结果保持一致，您可可以在输入中传入temperature 参数，并将该参数设置一个相对较小的值，比如temperature=0.1 或者 temperature=0.01。

是否支持提取 PDF 文档中的文本？

不支持。目前只支持图片输入。如需提取 PDF 文档中的文本，可以先将 PDF 转换成图片，然后再使用智能体处理转换得到的图片。

是否支持输入多张图片？

当前只支持输入单张图片，不支持输入多张图片。

参考信息

结构化卡证固定输出字段说明

银行卡识别

  • 输入图片样例
    alt

  • 固定输出字段

    字段

    类型

    说明

    备注

    number

    String

    卡号

    无

    expired_date

    String

    过期时间

    无

    bank_id

    String

    银行编号

    无

    bank_name

    String

    银行名称

    无

    card_name

    String

    卡名称

    无

  • 输出示例

    {
    "number": "6222628888888888888",
    "expired_date": "8888/88",
    "bank_id": "03010000",
    "bank_name": "交通银行",
    "card_name": "交银IC卡"
}

身份证识别

  • 输入图片样例
    alt

  • 固定输出字段

    字段

    类型

    说明

    备注

    name

    String

    姓名

    身份证正面

    gender

    String

    性别

    身份证正面

    ethnicity

    String

    民族

    身份证正面

    data_of_birth

    String

    出生

    身份证正面

    domicile

    String

    住址

    身份证正面

    id_number

    String

    公民身份号码

    身份证正面

    issue_authority

    String

    签发机关

    身份证反面

    valid_period

    String

    有效期限

    身份证反面

  • 输出示例

    {
    "name":"字节跑动",
    "gender":"男",
    "ethnicity":"汉",
    "data_of_birth":"1999.01.01",
    "domicile":"滨江市海滨区西知春路00号",
    "id_number":"102030199004444444",
    "issue_authority":"",
    "valid_period":""
}

驾驶证识别

  • 输入图片样例
    alt

  • 固定输出字段

    输出字段

    类型

    说明

    备注

    id_number

    String

    驾驶证号

    主页信息

    name

    String

    姓名

    主页信息

    sex

    String

    性别

    主页信息

    nationality

    String

    国籍

    主页信息

    address

    String

    住址

    主页信息

    date_of_birth

    String

    出生日期

    主页信息

    date_of_first_issue

    String

    初次领证日期

    主页信息

    driving_class

    String

    准驾车型

    主页信息

    valid_begin

    String

    有效期起

    主页信息

    valid_end

    String

    有效期止

    主页信息

    licence_issuing_authority

    String

    发证机关

    主页信息

    document_id

    String

    档案编号

    副页信息

    record

    String

    记录

    副页信息

  • 输出示例

    {
    "address": "山东省XX市XX镇XX村XX", 
    "class": "C1",
    "date_of_birth": "1959-01-09",
    "date_of_first_issue": "2013-12-27", 
    "document_id": "411300211186", 
    "id_number": "411328198921091120",
    "licence_issuing_authority": "河南省XX市公安局交通警察支队", 
    "name": "梁XX", 
    "nationality": "中国",
    "record": "实习期至2015年12月26日。", 
    "sex": "女", 
    "valid_begin": "2013-02-27", 
    "valid_end": "2018-12-27"
}

行驶证识别

  • 输入图片样例
    alt

  • 固定输出字段

    字段

    类型

    说明

    备注

    plate_number

    String

    号牌号码

    优先返回主页上的"号牌号码"，无主页时返回副页上的"号牌号码"

    vehicle_type

    String

    车辆类型

    主页信息

    owner

    String

    所有人

    主页信息

    address

    String

    住址

    主页信息

    use_character

    String

    使用性质

    主页信息

    model

    String

    品牌型号

    主页信息

    vin

    String

    车辆识别代号

    主页信息

    engine_number

    String

    发动机号码

    主页信息

    register_date

    String

    注册日期（YYYY.MM.DD）

    主页信息

    issue_date

    String

    发证日期（YYYY.MM.DD）

    主页信息

    licence_issuing_authority

    String

    发证机关

    主页信息

    document_id

    String

    档案编号

    副页信息

    approved_passengers_capacity

    String

    核定载人数

    副页信息

    total_mass

    String

    总质量

    副页信息

    curb_weight

    String

    整备质量

    副页信息

    ratified_load_capacity

    String

    核定载质量

    副页信息

    gabarite

    String

    外廓尺寸

    副页信息

    traction_mass

    String

    准牵引总质量

    副页信息

    remarks

    String

    备注

    副页信息

    inspection_record

    String

    检验记录

    副页信息

  • 输出示例

    {
    "address": "某某省某某县某某路",
    "approved_passengers_capacity": "XXXX",
    "curb_weight": "XXX", 
    "document_id": "XXX",
    "engine_number": "ABCDEF123456", 
    "gabarite": "XXX", 
    "inspection_record": "XXX", 
    "issue_date": "2014.01.01", 
    "licence_issuing_authority": "某某省某某市公安局交通警察支队", 
    "model": "桑塔纳12345ABCDE", 
    "owner": "张三", 
    "plate_number": "京ABCDEF", 
    "ratified_load_capacity": "", 
    "register_date": "2011.01.01", 
    "remarks": "XXX", 
    "total_mass": "XXX", 
    "traction_mass": "XXX", 
    "use_character": "非营运", 
    "vehicle_type": "小型轿车", 
    "vin": "ABCDCHGH123456789"
}

火车票识别

  • 输入图片样例
    alt

  • 固定输出字段

    字段

    类型

    说明

    备注

    ticket_num

    String

    票号

    主页信息

    start_station

    String

    出发站

    主页信息

    train_num

    String

    车次

    主页信息

    end_station

    String

    到达站

    主页信息

    time

    String

    出发时间

    主页信息

    seat_num

    String

    座位号

    主页信息

    price

    String

    价格

    主页信息

    seat_cls

    String

    座位等级

    主页信息

    id_num

    String

    证件号

    主页信息

    name

    String

    姓名

    主页信息

    sale_num

    String

    销售编号

    主页信息

    sale_station

    String

    售票车站

    主页信息

    sub_type

    String

    车票类型（正常票、补票等其他票）

    主页信息

  • 输出示例

    {
     "ticket_num":"Q099454",
     "start_station":"南京南",
     "train_num":"G124",
     "end_station":"北京南",
     "time":"2015年07月10日12:21开",
     "seat_num":"11车13A号",
     "price":"¥443.5元",
     "seat_cls":"二等座",
     "id_num":"341126********4921",
     "name":"王XX",
     "sale_num":"10010000490718Q099454",
     "sale_station":"北京南售",
     "sub_type":"normal_ticket"
}

增值税发票识别

  • 输入图片样例
    alt

  • 固定输出字段

    字段

    类型

    说明

    备注

    invoice_code

    String

    发票代码

    主页信息

    invoice_name

    String

    发票名称

    主页信息

    machine_num

    String

    机器编号

    主页信息

    check_code

    String

    校验码

    主页信息

    sheet_name

    String

    发票联次

    主页信息

    invoice_no

    String

    发票号码

    主页信息

    typed_invoice_code

    String

    机打发票代码

    主页信息

    typed_invoice_no

    String

    机打发票号码

    主页信息

    invoice_date

    String

    开票日期

    主页信息

    buyer_name

    String

    购买方名称

    主页信息

    buyer_taxpayer_no

    String

    购买方纳税人识别号

    主页信息

    buyer_account

    String

    购买方开户行&账号

    主页信息

    entry

    List of Entry

    应税条目

    字段说明见下方

    total_price

    String

    金额

    主页信息

    total_tax

    String

    税额

    主页信息

    big_total_price_and_tax

    String

    大写金额（价税合计）

    主页信息

    total_price_and_tax

    String

    小写金额（价税合计）

    主页信息

    seller_name

    String

    销售方

    主页信息

    seller_taxpayer_no

    String

    销售方识别号

    主页信息

    seller_address_phone

    String

    销售方地址&电话

    主页信息

    seller_account

    String

    销售方开户行&账号

    主页信息

    comment

    String

    备注

    主页信息

    payee

    String

    收款人

    主页信息

    reviewer

    String

    复核

    主页信息

    drawer

    String

    开票人

    主页信息

    entry 明细说明

    字段

    类型

    说明

    备注

    entry_name

    String

    货物或应税劳务、服务名称

    主页信息

    entry_type

    String

    型号

    主页信息

    unit

    String

    单位

    主页信息

    quantity

    String

    数量

    主页信息

    unit_price

    String

    单价（不含税）

    主页信息

    price_amount

    String

    金额

    主页信息

    tax_rate

    String

    税率

    主页信息

    tax_amount

    String

    税额

    主页信息

  • 输出示例

    {
    "invoice_code":"011002000611",
    "machine_num":"499098491560",
    "invoice_name":"XX增值税电子普通发票",
    "check_code":"16649652847559064366",
    "invoice_no":"10178760",
    "invoice_date":"2020年12月14日",
    "buyer_name":"北京字跳网络技术有限公司",
    "buyer_taxpayer_no":"91110108MA01F2L25J",
    "buyer_address_phone": "知春路1号 12xx24567222"，
    "entry": [{
        "entry_name":"*运输服务*客运服务费",
        "entry_type":"无",
        "unit":"次",
        "quantity":"1",
        "unit_prict":"73.92",
        "price_amount":"73.92",
        "tax_rate":"免税",
        "tax_amount":"***",
    }],
    "total_price":"73.92",
    "total_tax":"***",
    "big_total_price_and_tax":"柒拾叁圆玖角贰分",
    "total_price_and_tax":"73.92",
    "seller_name":"北京滴滴出行科技有限公司",
    "seller_taxpayer_no":"91110108MA01G0FB09",
    "seller_address_phone":"北京市海淀区东北旺西路8号院34号楼二层208号010-62682929",
    "seller_account":"招商银行股份有限公司北京东三环支行110936504210806",
    "payee":"张雪丽",
    "reviewer":"蔡静",
    "drawer":"杜洪亮",
}

印章识别

  • 输入图片样例
    Image

  • 固定输出字段
    以 list 输出。list 中每个元素表示一个印章。每个印章元素包含以下 3 个字段。

    字段

    类型

    说明

    说明

    company_name

    String

    印章内部单位名称

    无

    tax_code

    String

    印章内部税务代码

    无

    seal_type

    String

    印章内部专用章信息

    无

  • 输出示例

    {
    [
        "company_name":"宁波迅途信息技术有限公司",
        "tax_code":"913302820629019631",
        "seal_type":"发票专用章",
    ]
}