Laravel AI · 千问（Qwen）驱动

为 Laravel AI 提供阿里云百炼（DashScope）千问接入驱动。在官方 openai-compatible 驱动的文本对话 / 向量能力之上，补齐百炼平台的多模态扩展能力：

• 💬 文本对话 / 向量嵌入：继承官方 OpenAI 兼容驱动，对接百炼 Compatible Mode
• 🔊 Qwen-TTS 语音合成：DashScope 原生 multimodal-generation 端点（qwen3-tts-flash）
• 🎨 Qwen-Image 图像生成 / 编辑：DashScope 原生 multimodal-generation 端点（qwen-image-2.0-pro）
• 🎬 Wan 万相视频生成：异步任务模式（创建任务 → 轮询结果），支持文生视频 / 首尾帧图生视频

环境需求

• PHP ^8.4
• Laravel ^12.0 / ^13.0
• laravel/ai ^0.10.3
• 阿里云百炼 API Key（控制台获取）

安装

composer require larva/laravel-ai-qwen

包通过 Laravel Package Discovery 自动注册 qwen 驱动，无需手动添加 ServiceProvider。

配置

在 config/ai.php 的 providers 中新增百炼接入点：

'providers' => [
    // ...

    'qwen' => [
        'driver' => 'qwen',
        'key' => env('DASHSCOPE_API_KEY'),

        // 文本 / 向量走 OpenAI 兼容接口
        'url' => env('QWEN_BASE_URL', 'https://dashscope.aliyuncs.com/compatible-mode/v1'),

        // TTS / 图像 / 视频走百炼原生接口（与上面的 url 不同，必填）
        'api_url' => env('QWEN_API_URL', 'https://dashscope.aliyuncs.com/api/v1'),

        // 可选：默认模型与网关参数
        'models' => [
            'text' => [
                'default' => env('QWEN_TEXT_MODEL', 'qwen3.7-plus'), // 默认文本模型
            ],
            'embeddings' => [
                'default' => env('QWEN_EMBEDDINGS_MODEL', 'text-embedding-v4'), // 默认向量模型
                'dimensions' => env('QWEN_EMBEDDINGS_DIMENSIONS', 1024), // 向量维度
            ],
            'audio' => [
                'default' => env('QWEN_AUDIO_MODEL', 'qwen3-tts-flash'), // 默认 TTS 模型
                'voice' => env('QWEN_AUDIO_VOICE', 'Cherry'), // 默认女声
                'male_voice' => env('QWEN_AUDIO_MALE_VOICE', 'Ethan'), // 默认男声
                'language_type' => env('QWEN_AUDIO_LANGUAGE', 'Auto'), // Auto / Chinese / English / Japanese ...
                'format' => env('QWEN_AUDIO_FORMAT', 'wav'), // 仅用于返回结果的 MIME 类型与扩展名
            ],
            'image' => [
                'default' => env('QWEN_IMAGE_MODEL', 'qwen-image-2.0-pro'), // 默认图像模型
                'watermark' => false, // 是否添加水印
                'prompt_extend' => true, // 是否开启提示词智能改写
                // 'negative_prompt' => '模糊，低质量', // 可选负向提示词
            ],
            'video' => [
                'default' => env('QWEN_VIDEO_MODEL', 'wan3.0-video'), // 默认视频模型
            ],
        ],
    ],
],

.env：

DASHSCOPE_API_KEY=your-dashscope-api-key
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
QWEN_API_URL=https://dashscope.aliyuncs.com/api/v1

如需将千问设为默认提供方：

AI_DEFAULT_PROVIDER=qwen

新加坡等其它地域请将 url 与 api_url 分别替换为对应地域的 Compatible Mode 与原生接口地址。

使用

文本对话 / 向量嵌入

文本与向量能力继承自官方 OpenAI 兼容驱动，用法与 Laravel AI 官方文档 一致，将提供方指定为 qwen 即可：

use Laravel\Ai\Ai;

$embeddings = Ai::embeddingProvider('qwen')
    ->embeddings(['通义千问是阿里云推出的大模型'], model: 'text-embedding-v4');

TTS 语音合成

use Laravel\Ai\Ai;

$audio = Ai::audioProvider('qwen')->audio('你好，欢迎使用通义千问。');

$audio->store('greeting.wav', 'public');

SDK 占位音色 default-female / default-male 会映射为配置中的 voice / male_voice；也可以直接传入 Qwen 音色名称：

$audio = Ai::audioProvider('qwen')->audio(
    '今天天气真不错。',
    voice: 'Serena',
);

Qwen3-TTS 不支持 OpenAI 的 instructions 参数，情绪 / 语气通过音色与文本控制，该参数会被忽略。

非流式响应同时返回 Base64 音频与 24 小时有效的音频 URL，驱动优先使用 Base64，避免二次下载。

Qwen-Image 图像生成 / 编辑

use Laravel\Ai\Ai;

$image = Ai::imageProvider('qwen')->image(
    '一只在草地上奔跑的柴犬，阳光明媚，摄影风格',
    size: '3:2',
);

$image->store('shiba.png', 'public');

尺寸与质量映射规则：显式 size（支持 1:1 / 2:3 / 3:2 / 16:9 / 9:16 / 4:3 / 3:4 比例或 2048x2048 显式像素，统一转换为 宽*高）优先；未指定时 quality 映射为分辨率档位（low → 1024*1024、medium → 模型默认 2048*2048、high → 2048*2048）。

use Laravel\Ai\Files\RemoteImage;

// 图生图 / 图像编辑：支持 RemoteImage / LocalImage / StoredImage / Base64Image
$image = Ai::imageProvider('qwen')->image(
    '把背景换成海边',
    [new RemoteImage('https://example.com/ref.png')],
);

远端参考图会直接以 URL 透传，本地 / 存储盘文件会转为 Base64 Data URI 后提交。

Wan 万相视频生成

视频生成为百炼异步任务接口（SDK 暂无 VideoProvider 契约），由 QwenProvider 直接提供：

use Laravel\Ai\Ai;

/** @var \Larva\Ai\Qwen\Providers\QwenProvider $provider */
$provider = Ai::instance('qwen');

// 1. 创建任务（文生视频）
$task = $provider->createVideoTask('一只猫在草地上奔跑，镜头缓慢推进', [
    'duration' => 5,          // 时长（秒）
    'resolution' => '1080P',  // 480P / 720P / 1080P
    'ratio' => '16:9',        // adaptive / 16:9 / 9:16 / 1:1 / 4:3 / 3:4
    'watermark' => false,
    'prompt_extend' => true,
]);

// 图生视频：首帧 / 尾帧（万相 3.0 使用 media 数组）
$task = $provider->createVideoTask('让画面动起来', [
    'image' => 'https://example.com/first.png', // 等价于 first_frame
    'images' => [
        ['url' => 'https://example.com/last.png', 'role' => 'last_frame'],
    ],
]);

// 2. 轮询任务状态
$result = $provider->getVideoResult($task['task_id']);

// task_status：PENDING / RUNNING / SUCCEEDED / FAILED / CANCELED / UNKNOWN
if ($result['task_status'] === 'SUCCEEDED') {
    $videoUrl = $result['video_url']; // URL 有效期 24 小时
}

createVideoTask() 与 getVideoResult() 均返回 DashScope 的 output 字段。任务 ID 与生成结果 URL 的有效期均为 24 小时，请及时下载视频。

也支持通过 media 直接传入万相原生媒体数组，或通过 input / parameters 覆盖请求参数。

异常处理

网关统一使用 Laravel AI 的异常体系，可在调用处捕获：

• Laravel\Ai\Exceptions\RateLimitedException：触发限流
• Laravel\Ai\Exceptions\InsufficientCreditsException：余额不足
• Laravel\Ai\Exceptions\ProviderOverloadedException：服务过载
• Illuminate\Http\Client\RequestException：其它 HTTP 错误

开发与测试

composer install
composer test          # 运行单元测试
composer check-style   # 代码风格检查
composer fix-style     # 自动修复代码风格

贡献

欢迎提交 Issue 与 Pull Request。提交前请：

1. 通过 composer test 全部测试
2. 通过 composer check-style 风格检查
3. 在 PR 中描述清楚变更背景与影响范围

安全

如发现安全漏洞，请联系：xutongle@msn.com，请勿在公开 Issue 中披露。

许可证

本项目基于 MIT 协议发布。