跳转到主要内容
文本

文字提取(Qwen-OCR)

Qwen-OCR 是专为文字提取设计的视觉理解模型,支持从扫描文档、表格、票据等各类图像中提取文本或结构化数据,覆盖多语言场景,并内置信息抽取、表格解析、公式识别等高级任务。

Qwen-OCR 可从扫描文件、表格、收据等图片中提取文字并解析结构化数据,支持多语言识别、信息提取、表格解析和公式识别。 模型体验: 千问AI平台

示例

多语言识别

输入图片
image
识别结果INTERNATIONALMOTHER LANGUAGEDAYПривет!你好!Bonjour!Merhaba!Ciao!Hello!Ola!בר מולדSalam!

倾斜图片识别

输入图片
image
识别结果产品介绍本品采用韩国进口纤维丝制造,不缩水、不变形、不发霉、不生菌、不伤物品表面。具有真正的不粘油、吸水力强、耐水浸、清洗干净、无毒、无残留、易晾干等特点。店家使用经验:不锈钢、陶瓷制品、浴盆、整体浴室大部分是白色的光洁表面,用其他的抹布擦洗表面污渍不易洗掉,太尖的容易划出划痕。使用这个仿真丝瓜布,沾少量中性洗涤剂揉出泡沫,很容易把这些表面污渍擦洗干净。6941990612023货号:2023

文字位置定位

输入图片
img_1
高精识别任务支持文字定位功能。
识别结果定位可视化
img_1_location
如何将每行文本的边界框绘制到原图上,请参见 FAQ。

模型选型

Qwen-OCR 提供以下模型,请根据业务需求选择:
  • Qwen3.5-OCR:基于 Qwen3.5 架构,在文档解析、文字定位、关键信息提取等方面全面升级。支持多轮对话、PDF 文档解析。在业务卡证(身份证、驾驶证等)信息抽取场景效果显著提升,支持的卡证种类请参见支持的证照与票据类型。包括 qwen3.5-ocr 模型。
  • Qwen-VL-OCR:基于 Qwen3-VL 架构,支持文档解析、文字定位(高精识别)、信息抽取、表格解析、公式识别、通用文字识别、多语言识别等内置任务,支持图像旋转矫正。包括 qwen-vl-ocr(稳定版)和 qwen-vl-ocr-2025-11-20 模型。
  • 早期版本(不推荐):功能和效果均不及新版本,建议迁移至 qwen3.5-ocr。包括 qwen-vl-ocr-2024-10-28 模型。
qwen-vl-ocr 模型的 max_tokens 参数(最大输出长度)默认为 4096。如需将该参数调高至 4097~8192 范围,请联系商务经理进行申请,并提供:主账号 ID、图像类型(文档图、电商图、合同等)、模型名称、预计 QPS 和每日请求总量,以及输出长度超过 4096 的请求占比。

前提条件

  • 获取 API Key 并将其设置为环境变量。
  • 如果使用 OpenAI SDK 或 DashScope SDK,请先安装最新版 SDK。DashScope Python SDK 最低版本为 2.0.1,Java SDK 最低版本为 2.21.8。
    • DashScope SDK
      • 优势:支持图像旋转矫正、内置 OCR 任务等所有高级特性,功能完整,调用简洁。
      • 适用场景:需要使用完整功能的项目。
    • OpenAI 兼容 SDK
      • 优势:已使用 OpenAI SDK 或生态工具的项目可快速迁移。
      • 限制:高级功能(图像旋转矫正和内置 OCR 任务)不支持直接通过参数调用,需手动构造 Prompt 模拟,输出结果需自行解析。
      • 适用场景:已有 OpenAI 集成、且不依赖 DashScope 专有高级功能的项目。

快速开始

以下示例从火车票图片(URL)中提取关键信息并以 JSON 格式返回。本地文件上传和图片限制,请参见如何传入本地文件和图片限制。
  • OpenAI 兼容-Chat
  • OpenAI 兼容-Response
  • DashScope
from openai import OpenAI
import os

PROMPT_TICKET_EXTRACTION = """
请提取车票图像中的发票号码、车次、起始站、终点站、发车日期和时间点、座位号、席别类型、票价、身份证号码、购票人姓名。
要求准确无误的提取上述关键信息、不要遗漏和捏造虚假信息,模糊或者强光遮挡的单个文字可以用英文问号?代替。
返回数据格式以json方式输出,格式为:{'发票号码':'xxx', '车次':'xxx', '起始站':'xxx', '终点站':'xxx', '发车日期和时间点':'xxx', '座位号':'xxx', '席别类型':'xxx','票价':'xxx', '身份证号码':'xxx', '购票人姓名':'xxx'}
"""

try:
  client = OpenAI(
    # 若没有配置环境变量,请用 API Key 将下行替换为:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
  )
  completion = client.chat.completions.create(
    model="qwen3.5-ocr",
    messages=[
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {"url":"https://img.alicdn.com/imgextra/i2/O1CN01ktT8451iQutqReELT_!!6000000004408-0-tps-689-487.jpg"},
            # 输入图像的最小像素阈值,小于该值图像会进行放大,直到总像素大于min_pixels
            "min_pixels": 32 * 32 * 3,
            # 输入图像的最大像素阈值,超过该值图像会进行缩小,直到总像素低于max_pixels
            "max_pixels": 32 * 32 * 8192
          },
          # 模型支持在text字段中传入Prompt,若未传入,则会使用默认的Prompt:Please output only the text content from the image without any additional descriptions or formatting.
          {"type": "text",
          "text": PROMPT_TICKET_EXTRACTION}
        ]
      }
    ])
  print(completion.choices[0].message.content)
except Exception as e:
  print(f"错误信息: {e}")
{
  "choices": [{
    "message": {
      "content": "```json\n{\n    \"发票号码\": \"24329116804000\",\n    \"车次\": \"G1948\",\n    \"起始站\": \"南京南站\",\n    \"终点站\": \"郑州东站\",\n    \"发车日期和时间点\": \"2024年11月14日11:46开\",\n    \"座位号\": \"04车12A号\",\n    \"席别类型\": \"二等座\",\n    \"票价\": \"¥337.50\",\n    \"身份证号码\": \"4107281991****5515\",\n    \"购票人姓名\": \"读小光\"\n}\n```",
      "role": "assistant"
    },
    "finish_reason": "stop",
    "index": 0,
    "logprobs": null
  }],
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 606,
    "completion_tokens": 159,
    "total_tokens": 765
  },
  "created": 1742528311,
  "system_fingerprint": null,
  "model": "qwen3.5-ocr",
  "id": "chatcmpl-20e5d9ed-e8a3-947d-bebb-c47ef1378598"
}

调用内置任务

为简化特定场景下的调用,模型(qwen-vl-ocr-2024-10-28 除外)内置了多种任务。 调用方式:
  • DashScope SDK:设置 ocr_options 参数即可调用内置任务。qwen3.5-ocr 起,定制任务与用户自定义 Prompt 结合使用(不再强制覆盖),定制任务结果通过 ocr_result 字段返回。早期版本模型内部使用固定 Prompt。
  • OpenAI 兼容 SDK:需手动传入任务指定的 Prompt。
以下标签页列出了各内置任务对应的 task 取值、指定的 Prompt、输出格式、示例及调用代码。
  • 高精识别
  • 信息抽取
  • 表格解析
  • 文档解析
  • 公式识别
  • 通用文字识别
  • 多语言识别
推荐使用 qwen-vl-ocr-2025-11-20 及以后版本模型,支持:
  • 文本内容识别(提取文字)
  • 文本位置检测(定位文本行并输出坐标)
获取文本边界框坐标后,如何将检测框绘制到原图上,请参见 FAQ。
task 值:advanced_recognition指定的 Prompt:
定位所有的文字行,并且返回旋转矩形([cx, cy, width, height, angle])的坐标结果。
输出格式:纯文本,或从 ocr_result 字段中直接获取 JSON 对象。字段说明:
  • text:每行的文本内容。
  • rotate_rect:文字框的旋转矩形表示,示例值:[center_x, center_y, width, height, angle]。其中 center_x、center_y 为文本框中心点坐标,width 为宽度,height 为高度,angle 为文本框相对于水平方向的旋转角度,取值范围为 [-90, 90]。
  • location:文字框四个顶点的绝对坐标,示例值:[x1, y1, x2, y2, x3, y3, x4, y4]。以原图左上角为原点 (0,0),顶点顺序固定为左上、右上、右下、左下。
输出示例:
{
  "output": {
    "choices": [
      {
        "message": {
          "content": [
            {
              "ocr_result": {
                "words_info": [
                  {
                    "rotate_rect": [398,153,134,27,90],
                    "text": "Magsafe"
                  },
                  {
                    "rotate_rect": [680,250,40,167,90],
                    "text": "金盾系列"
                  },
import os
import dashscope

dashscope.base_http_api_url = "https://maas.qianwenaiapi.com/api/v1"

messages = [{
      "role": "user",
      "content": [{
        "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg",
        # 输入图像的最小像素阈值,小于该值图像会进行放大,直到总像素大于min_pixels
        "min_pixels": 32 * 32 * 3,
        # 输入图像的最大像素阈值,超过该值图像会进行缩小,直到总像素低于max_pixels
        "max_pixels": 32 * 32 * 8192,
        # 是否开启图像自动转正功能
        "enable_rotate": False}]
      }]

response = dashscope.MultiModalConversation.call(
  # 若没有配置环境变量,请用 API Key 将下行替换为:api_key="sk-xxx",
  api_key=os.getenv('DASHSCOPE_API_KEY'),
  model='qwen3.5-ocr',
  messages=messages,
  # 设置内置任务为高精识别
  ocr_options={"task": "advanced_recognition"}
)
# 高精识别任务的文本与坐标结果从 ocr_result 字段中获取
print(response["output"]["choices"][0]["message"].content[0]["ocr_result"])
{
  "output":{
    "choices":[
      {
        "finish_reason":"stop",
        "message":{
          "role":"assistant",
          "content":[
            {
              "text":"```json\n[{\"pos_list\": [{\"rotate_rect\": [740, 374, 599, 1459, 90]}]}```",
              "ocr_result":{
                "words_info":[
                  {
                    "rotate_rect":[150,80,49,197,-89],
                    "text":"读者对象"
                  },
                  {
                    "rotate_rect":[724,171,34,1346,-89],
                    "text":"如果你是Linux环境下的系统管理员,那么学会编写shell脚本将让你受益匪浅。本书并未细述安装"
                  },
                  {
                    "rotate_rect":[745,216,34,1390,-89],
                    "text":"Linux系统的每个步骤,但只要系统已安装好Linux并能运行起来,你就可以开始考虑如何让一些日常"
                  },
                  {
                    "rotate_rect":[748,263,34,1394,-89],
                    "text":"的系统管理任务实现自动化。这时shell脚本编程就能发挥作用了,这也正是本书的作用所在。本书将"
                  },
                  {
                    "rotate_rect":[749,308,34,1395,-89],
                    "text":"演示如何使用shell脚本来自动处理系统管理任务,包括从监测系统统计数据和数据文件到为你的老板"
                  },
                  {
                    "rotate_rect":[123,354,33,146,-89],
                    "text":"生成报表。"
                  },
                  {
                    "rotate_rect":[751,432,34,1402,-89],
                    "text":"如果你是家用Linux爱好者,同样能从本书中获益。现今,用户很容易在诸多部件堆积而成的图形环境"
                  },
                  {
                    "rotate_rect":[755,477,31,1404,-89],
                    "text":"中迷失。大多数桌面Linux发行版都尽量向一般用户隐藏系统的内部细节。但有时你确实需要知道内部"
                  },
                  {
                    "rotate_rect":[752,523,34,1401,-89],
                    "text":"发生了什么。本书将告诉你如何启动Linux命令行以及接下来要做什么。通常,如果是执行一些简单任"
                  },
                  {
                    "rotate_rect":[747,569,34,1395,-89],
                    "text":"务(比如文件管理),在命令行下操作要比在华丽的图形界面下方便得多。在命令行下有大量的命令"
                  },
                  {
                    "rotate_rect":[330,614,34,557,-89],
                    "text":"可供使用,本书将会展示如何使用它们。"
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  },
  "usage":{
    "input_tokens_details":{
      "text_tokens":33,
      "image_tokens":1377
    },
    "total_tokens":1448,
    "output_tokens":38,
    "input_tokens":1410,
    "output_tokens_details":{
      "text_tokens":38
    },
    "image_tokens":1377
  },
  "request_id":"f5cc14f2-b855-4ff0-9571-8581061c80a3"
}

PDF 文档解析

qwen3.5-ocr 支持通过 Response API 直接传入 PDF 文件进行文档解析,无需手动将 PDF 拆分为图片,且输出长度不受模型最大输出长度限制,可完整解析长文档。仅支持 Response API 调用,不支持 Chat API。PDF 文件限制:不超过 100 MB;页数上限取决于 ocr_options 中的 task,设置为 document_parsing 时最大 50 页,未设置 task 或设置为其他任务时最大 10 页。 以下示例通过 Response API 传入 PDF 文件进行文档解析。
import os
from openai import OpenAI

client = OpenAI(
  # 若没有配置环境变量,请用 API Key 将下行替换为:api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
)

response = client.responses.create(
  model="qwen3.5-ocr",
  input=[{
    "role": "user",
    "content": [{
      "type": "input_file",
      "file_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260616/qmycjl/1506.02640v5.pdf"
    }]
  }],
  extra_body={
    "ocr_options": {"task": "document_parsing"}
  }
)

# 获取定制任务结果
print(response.output[0].content[0].ocr_result)
如使用不支持 Response API 的早期模型(qwen-vl-ocr-2025-11-20 及之前),可使用图像处理库(如 Python 的 pdf2image)将 PDF 按页转换为图片后,参照多图像输入逐页识别。
关于 OpenAI Responses API 的更多用法(如获取和管理已完成的模型响应),请参见OpenAI 兼容 - Responses。

传入本地文件(Base64 编码或文件路径)

Qwen-OCR 支持两种本地文件上传方式:Base64 编码和文件路径。根据文件大小和 SDK 类型选择合适的方式(参见如何选择文件上传方式),两种方式均需满足图片限制中的图像规格要求。
  • 使用 Base64 编码
  • 使用文件路径
将文件转换为 Base64 编码字符串后传入模型。此方式适用于 OpenAI SDK、DashScope SDK 和 HTTP 请求。
1

编码文件

将本地图片转换为 Base64 编码字符串。
# Encoding function: Converts a local file to a Base64-encoded string.
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode("utf-8")

# Replace xxx/eagle.png with the absolute path of your local image.
base64_image = encode_image("xxx/eagle.png")
2

构造 Data URL

按以下格式构造 Data URL:data:[MIME_type];base64,<base64_image>。
  1. 将 MIME_type 替换为实际的媒体类型,确保与图片限制表中的 MIME type 值一致,例如 image/jpeg 或 image/png。
  2. base64_image 为上一步生成的 Base64 编码字符串。
3

调用模型

通过 image 或 image_url 参数传入 Data URL 来调用模型。

传入文件路径

传入文件路径仅支持 DashScope Python SDK 和 Java SDK,不支持 DashScope HTTP 或 OpenAI 兼容方式。
import os
import dashscope

client = dashscope.Client(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qianwenaiapi.com/api/v1",
)

# 将xxxx/test.png替换为您本地图像的绝对路径
local_path = "xxx/test.jpg"
image_path = f"file://{local_path}"
messages = [
  {
    "role": "user",
    "content": [
      {
        "image": image_path,
        # 输入图像的最小像素阈值,小于该值图像会进行放大,直到总像素大于min_pixels
        "min_pixels": 32 * 32 * 3,
        # 输入图像的最大像素阈值,超过该值图像会进行缩小,直到总像素低于max_pixels
        "max_pixels": 32 * 32 * 8192,
      },
      # 模型未设置内置任务时,支持在text字段中传入Prompt,若未传入则使用默认的Prompt:Please output only the text content from the image without any additional descriptions or formatting.
      {
        "text": "请提取车票图像中的发票号码、车次、起始站、终点站、发车日期和时间点、座位号、席别类型、票价、身份证号码、购票人姓名。要求准确无误的提取上述关键信息、不要遗漏和捏造虚假信息,模糊或者强光遮挡的单个文字可以用英文问号?代替。返回数据格式以json方式输出,格式为:{'发票号码':'xxx', '车次':'xxx', '起始站':'xxx', '终点站':'xxx', '发车日期和时间点':'xxx', '座位号':'xxx', '席别类型':'xxx','票价':'xxx', '身份证号码':'xxx', '购票人姓名':'xxx'}"
      },
    ],
  }
]

response = client.multimodal.chat.create(
  model="qwen3.5-ocr",
  messages=messages,
)
print(response.output_text)

传入 Base64 编码字符串

  • OpenAI 兼容
  • DashScope
  • Python
  • Node.js
  • curl
from openai import OpenAI
import os
import base64

#  读取本地文件,并编码为 Base64 格式
def encode_image(image_path):
  with open(image_path, "rb") as image_file:
    return base64.b64encode(image_file.read()).decode("utf-8")

# 将xxxx/test.png替换为您本地图像的绝对路径
base64_image = encode_image("xxx/test.png")

client = OpenAI(
  # 若没有配置环境变量,请用 API Key 将下行替换为:api_key="sk-xxx"
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qianwenaiapi.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
  model="qwen3.5-ocr",
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "image_url",
          # 需要注意,传入Base64,图像格式(即image/{format})需要与支持的图片列表中的Content Type保持一致。"f"是字符串格式化的方法。
          # PNG图像:  f"data:image/png;base64,{base64_image}"
          # JPEG图像: f"data:image/jpeg;base64,{base64_image}"
          # WEBP图像: f"data:image/webp;base64,{base64_image}"
          "image_url": {"url": f"data:image/png;base64,{base64_image}"},
          # 输入图像的最小像素阈值,小于该值图像会进行放大,直到总像素大于min_pixels
          "min_pixels": 32 * 32 * 3,
          # 输入图像的最大像素阈值,超过该值图像会进行缩小,直到总像素低于max_pixels
          "max_pixels": 32 * 32 * 8192
        },
        # 模型支持在以下text字段中传入Prompt,若未传入,则会使用默认的Prompt:Please output only the text content from the image without any additional descriptions or formatting.
        {"type": "text", "text": "请提取车票图像中的发票号码、车次、起始站、终点站、发车日期和时间点、座位号、席别类型、票价、身份证号码、购票人姓名。要求准确无误的提取上述关键信息、不要遗漏和捏造虚假信息,模糊或者强光遮挡的单个文字可以用英文问号?代替。返回数据格式以json方式输出,格式为:{'发票号码':'xxx', '车次':'xxx', '起始站':'xxx', '终点站':'xxx', '发车日期和时间点':'xxx', '座位号':'xxx', '席别类型':'xxx','票价':'xxx', '身份证号码':'xxx', '购票人姓名':'xxx'}"},

      ],
    }
  ],
)
print(completion.choices[0].message.content)

更多用法

限制说明

图片限制

  • 尺寸与宽高比:图片宽度和高度均须大于 10 像素,宽高比不得超过 200:1 或 1:200。
  • 总像素数:无严格限制,模型会自动缩放;建议不超过 1568 万像素。
  • 支持的图片格式
    • 分辨率低于 4K (3840x2160) 的图片,支持以下格式:
      图片格式常见扩展名MIME 类型
      BMP.bmpimage/bmp
      JPEG.jpe, .jpeg, .jpgimage/jpeg
      PNG.pngimage/png
      TIFF.tif, .tiffimage/tiff
      WEBP.webpimage/webp
      HEIC.heicimage/heic
    • 分辨率在 4K(3840x2160) 至 8K(7680x4320) 之间的图片,仅支持 JPEG、JPG 和 PNG 格式。
  • 图片大小:
    • 通过公网 URL 或本地路径传入图片时,qwen3.5-ocr 单张图片不得超过 20 MB,其他版本不得超过 10 MB。
    • 通过 Base64 编码传入时,编码后的字符串不得超过 10 MB。
如需了解如何将图片或视频压缩至所需大小,请参见如何压缩图片或视频至所需大小。

模型限制

  • 系统消息:Qwen-OCR 不支持自定义 System Message,使用固定的内置 System Message。所有指令须通过 User Message 传入。
  • 多轮对话:qwen3.5-ocr 起支持多轮对话,可不传入图片 URL 进行纯文本追问。qwen-vl-ocr-2025-11-20 及更早版本仅处理最新一条消息,不保留上下文。
  • 幻觉风险:若图片中的文字过小或分辨率过低,模型可能产生幻觉。此外,对于与文字提取无关的问题,回答准确性无法保证。
  • 文本文件处理限制:对于包含多页或多张图片的文件(如转换为图片的 PDF 文档),请参照上线建议将其转换为图片序列后再进行处理。
  • 纯文本或结构化数据文件:Qwen-OCR 无法处理此类文件,请使用 Qwen-Long 等长文本模型处理。

支持的证照与票据类型

信息抽取任务支持从以下常见证照、票据、许可证中提取结构化信息。
  • 护照与出入境证件:中国护照、澳门护照、往来港澳通行证、往来台湾通行证、港澳居民来往内地通行证。
  • 车辆证件与交易发票:机动车驾驶证、机动车铭牌、车辆合格证、机动车登记证、机动车销售统一发票、二手车销售发票。
  • 发票与税收票据:增值税普通发票(卷票)、定额专用发票、通用机打发票、税收完税证明、中央非税收入统一票据。
  • 交通出行票据:12306 高铁票、火车票、船票、高速公路车辆通行费票据、高速公路机打发票。
  • 金融卡证与票据:信用卡、电子银行承兑汇票、收款收据、社会保障卡。
  • 营业执照与经营许可:营业执照、食品经营许可证、食品生产许可证、药品经营许可证、医疗器械经营许可证。
  • 不动产权证:不动产权证书。
  • 境外身份证件:香港身份证、澳门身份证、印度尼西亚身份证、泰国身份证、越南身份证、马来西亚身份证、菲律宾身份证、印度身份证、土耳其身份证、巴基斯坦身份证、墨西哥身份证、英国身份证、美国身份证。
  • 境外护照与驾照:印度护照、新加坡护照、泰国护照、美国护照、澳大利亚护照、阿联酋护照、菲律宾驾照、日本驾照、美国驾照。

计费与限流

  • 计费:Qwen-OCR 为多模态模型,总费用 = 输入 token 数 × 输入单价 + 输出 token 数 × 输出单价。各模型价格请参见模型市场。
    • 计算图像的 Token:可通过以下代码估算图像 token 用量,实际计费以 API 响应为准。
计算公式:图像 token 数 = (h_bar * w_bar) / token_pixels + 2。
  • h_bar * w_bar 是模型预处理后的图像尺寸。模型在推理前会将图像缩放至像素上限以内,该上限由 max_pixels 参数决定。
  • token_pixels 表示每个 Token 对应的像素数:
    • qwen3.5-ocr、qwen-vl-ocr、qwen-vl-ocr-2025-11-20 固定为 32*32(即 1024)。
    • 其他模型固定为 28*28(即 784)。
以下代码演示模型内部的图像缩放逻辑,可用于估算 token 用量,实际计费以 API 响应为准。
import math
from PIL import Image

def smart_resize(image_path, min_pixels, max_pixels):
  """
  对图像进行预处理。

  参数:
    image_path:图像的路径
  """
  # 打开指定的PNG图片文件
  image = Image.open(image_path)

  # 获取图片的原始尺寸
  height = image.height
  width = image.width
  # 将高度调整为28或32的整数倍
  h_bar = round(height / 32) * 32
  # 将宽度调整为28或32的整数倍
  w_bar = round(width / 32) * 32

  # 对图像进行缩放处理,调整像素的总数在范围[min_pixels,max_pixels]内
  if h_bar * w_bar > max_pixels:
    beta = math.sqrt((height * width) / max_pixels)
    h_bar = math.floor(height / beta / 32) * 32
    w_bar = math.floor(width / beta / 32) * 32
  elif h_bar * w_bar < min_pixels:
    beta = math.sqrt(min_pixels / (height * width))
    h_bar = math.ceil(height * beta / 32) * 32
    w_bar = math.ceil(width * beta / 32) * 32
  return h_bar, w_bar

# 将xxx/test.png替换为您本地的图像路径
h_bar, w_bar = smart_resize("xxx/test.png", min_pixels=32 * 32 * 3, max_pixels=8192 * 32 * 32)
print(f"缩放后的图像尺寸为:高度为{h_bar},宽度为{w_bar}")

# 计算图像的Token数:总像素除以32 * 32
token = int((h_bar * w_bar) / (32 * 32))

# <|vision_bos|> 和 <|vision_eos|> 作为视觉标记,每个需计入 1个Token
print(f"图像的总Token数为{token + 2}")
  • 限流:Qwen-OCR 模型的限流规则参见限流。
  • 免费额度:新用户可享受免费额度,详见免费额度。

上线建议

  • 图片预处理:
    • 确保输入图片清晰、光照均匀、未过度压缩:
      • 为避免信息丢失,存储和传输图片时使用无损格式(如 PNG)。
      • 为提升图片清晰度,使用均值滤波或中值滤波等去噪算法平滑噪声图片。
      • 为解决光照不均问题,使用自适应直方图均衡化等算法调整亮度和对比度。
    • 倾斜图片:使用 DashScope SDK 的 enable_rotate: true 参数可显著提升识别效果。
    • 尺寸过小或过大的图片:使用 min_pixels 和 max_pixels 参数控制图片在处理前的缩放方式。
      • min_pixels:放大小图片以提升细节检测效果,保持默认值即可。
      • max_pixels:防止超大图片消耗过多资源。大多数场景下默认值已足够;若小字体识别不清晰,可适当增大该值(注意会增加 Token 消耗)。
  • 结果验证:模型识别结果可能存在误差,对于关键业务操作,建议增加人工审核流程或验证规则以核实模型输出的准确性。例如,对身份证号、银行卡号等进行格式校验。
  • 批量调用:在大规模、非实时场景中,使用批处理 API 异步处理批量任务,成本更低。

FAQ

根据 SDK 类型、文件大小和网络稳定性选择最佳上传方式。
类型规格DashScope SDK(Python、Java)OpenAI 兼容 / DashScope HTTP
图片大于 7 MB 小于 20 MB传入本地路径仅支持公网 URL,建议使用对象存储服务。
小于 7 MB传入本地路径Base64 编码
  • Base64 编码会增大数据体积约 33%,原始文件应小于 7 MB。
  • Base64 和本地路径方式无需服务端下载,网络不稳定时稳定性更高。
获取模型输出的文字定位结果后,参照 draw_bbox.py 代码将检测框及标签绘制到原图上。
使用 qwen3.5-ocr 时,如果自定义 Prompt 中包含完整的 HTML 结构(例如 <html><body>...</body></html>),模型可能沿用该结构,将 OCR 结果以 HTML 格式返回,而非纯文本,此时返回内容看起来像是空内容或带前端标签的内容。仅包含简单标签(例如单个 <br>)不会触发该现象。可按以下任一方式处理:
  • 检查 Prompt 是否包含完整的 HTML 标签结构。如有,改用纯文本指令重试。例如将 <html><body>请提取图片中的所有文字</body></html> 改为 请提取图片中的所有文字。
  • 若不确定 Prompt 是否会影响输出格式,可不传 text 字段,使用模型默认的 Prompt。
  • 改用 qwen3.7-plus 模型,该模型传入相同的 HTML 结构 Prompt 仍返回纯文本结果。

API 参考

Qwen-OCR 模型的输入输出参数详见 Qwen-OCR API 参考。

错误码

如果模型调用失败并返回报错信息,请参见错误码进行解决。