qwen/image-ocr

基于通义千问大模型的图片文字识别与JSON结构化输出库

dev-main 2026-04-29 10:10 UTC

Requires

• php: >=7.2
• guzzlehttp/guzzle: ^6.5|^7.0

Requires (Dev)

• phpunit/phpunit: ^8.0

MIT

• image
• OCR
• ai
• llm
• qwen
• dashscope

README

基于通义千问大模型（qwen-vl-plus）的图片文字识别与 JSON 结构化输出库。

特性

• ✅ 基于 PHP 7.2+，使用 Guzzle HTTP 客户端
• ✅ 调用通义千问视觉模型识别图片中的文字
• ✅ 自动解析模型返回的 JSON 结构化数据
• ✅ 支持自定义 Prompt 指令
• ✅ 完善的异常处理与错误提示

安装

composer require qwen/image-ocr

快速开始

基础用法

<?php
require 'vendor/autoload.php';

use Qwen\ImageOcr\Client;

// 初始化客户端（使用你的 API Key）
$client = new Client('sk-dcefc4935b8c4211a7a711256e1491bb');

// 识别图片
$result = $client->recognize('https://example.com/image.jpg');

// 获取结构化数据
print_r($result->getData());

// 输出为 JSON 字符串
echo $result->toJson();

使用自定义 Prompt

$instruction = '请识别图片中的所有文字，并按表格形式输出为 JSON';
$result = $client->recognizeWithPrompt('https://example.com/table.jpg', $instruction);
echo $result->toJson();

使用 Base64 图片

$base64Image = 'data:image/jpeg;base64,/9j/4AAQSkZJRg...';
$result = $client->recognize($base64Image);

API 文档

Client

__construct($apiKeyOrConfig, array $options = [])

创建客户端实例。

参数：

• $apiKeyOrConfig：API Key 字符串或 Config 实例
• $options：可选配置数组
  • base_url：API 端点（默认：https://dashscope.aliyuncs.com/compatible-mode/v1）
  • model：模型名称（默认：qwen-vl-plus）
  • timeout：请求超时秒数（默认：60）

示例：

// 使用默认配置
$client = new Client('sk-xxxxxxxx');

// 自定义配置
$client = new Client('sk-xxxxxxxx', [
    'timeout' => 120,
    'model'   => 'qwen-vl-max',
]);

recognize(string $imageUrl): OcrResult

识别图片中的文字并返回结构化结果。

参数：

• $imageUrl：图片 URL 或 base64 data URI

返回：

• OcrResult 实例

异常：

• ApiException：API 请求失败
• OcrException：JSON 解析失败

recognizeWithPrompt(string $imageUrl, string $instruction): OcrResult

使用自定义 Prompt 识别图片。

参数：

• $imageUrl：图片 URL 或 base64 data URI
• $instruction：自定义指令文本

返回：

• OcrResult 实例

OcrResult

getData(): array

获取解析后的结构化数组。

getRawText(): string

获取模型返回的原始文本（可能包含 Markdown 代码块）。

getRawResponse(): array

获取完整的 API 响应数组。

toJson(int $flags = JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT): string

将结构化数据序列化为 JSON 字符串。

get(string $key, $default = null): mixed

快捷访问结构化数据中的某个键。

$title = $result->get('title', '无标题');

异常处理

use Qwen\ImageOcr\Exception\ApiException;
use Qwen\ImageOcr\Exception\OcrException;

try {
    $result = $client->recognize($imageUrl);
} catch (ApiException $e) {
    // API 请求失败（网络错误、认证失败等）
    echo "API 错误：" . $e->getMessage();
    echo "状态码：" . $e->getStatusCode();
    echo "响应体：" . $e->getResponseBody();
} catch (OcrException $e) {
    // JSON 解析失败或其他业务错误
    echo "OCR 错误：" . $e->getMessage();
}

高级用法

自定义 PromptBuilder

use Qwen\ImageOcr\Prompt\PromptBuilder;

$builder = new PromptBuilder('请识别图片中的发票信息，输出为 JSON');
$client->setPromptBuilder($builder);

$result = $client->recognize($imageUrl);

使用 Config 对象

use Qwen\ImageOcr\Config;
use Qwen\ImageOcr\Client;

$config = new Config('sk-xxxxxxxx', [
    'base_url' => 'https://custom-endpoint.com/v1',
    'model'    => 'qwen-vl-max',
    'timeout'  => 90,
]);

$client = new Client($config);

默认 Prompt

库内置的默认 Prompt 会要求模型：

1. 提取图片中的全部文字，保持原有顺序与层级关系
2. 分析文字的语义结构（标题、正文、表格、列表等）
3. 以标准 JSON 格式输出，结构示例：

   {
     "texts": ["识别到的文字1", "识别到的文字2"],
     "structured": {
       "title": "...",
       "body": "...",
       "tables": [],
       "key_values": {}
     },
     "summary": "对图片内容的简短描述"
   }

你可以通过 recognizeWithPrompt() 或 setPromptBuilder() 自定义 Prompt。

系统要求

• PHP >= 7.2
• Guzzle HTTP 客户端 ^6.5 或 ^7.0

许可证

MIT License

相关链接

• 通义千问 DashScope 文档
• Guzzle HTTP 客户端