上周刷 Laravel 的动态，看到官方出了个 AI 框架，就叫 laravel/ai。
文本对话、向量嵌入、语音、画图，接口全部定义好了，还给了统一的 Facade。
我的第一反应是，PHP 终于有官方的 AI 入口了。
第二反应是，默认驱动清一色 OpenAI。
不是 OpenAI 不好。是国内用起来太别扭，网络要折腾，账单算美元，出了问题连个能中文沟通的工单都没有。
对国内开发者来说，更顺手的选择其实是通义千问。阿里云百炼平台，国内直连，按量付费，发票齐全。
所以我花了一个周末，给 laravel/ai 写了个千问驱动。
今天把它开源出来，包名叫 laravel-ai-qwen。
01
一个包，五种能力
这个包做的事，一句话能说清。
让 Laravel 应用通过一个驱动，用上阿里云百炼的全套千问能力。
具体五样，一屏看清楚。
💬文本对话OpenAI 兼容模式
官方用法零改动🧭向量嵌入text-embedding-v4
维度可配🔊语音合成Qwen3-TTS
多音色可选🎨图像生成Qwen Image
生成加改图🎬视频生成Wan 万相
文生加图生
前三样，官方定义了接口契约，我负责实现。文本和向量直接继承官方的 OpenAI 兼容驱动，对接百炼的 Compatible Mode，用法和官方文档一模一样。
语音和图像这两样，官方有契约，但 OpenAI 那套参数和百炼对不上，我做了完整的映射。
视频官方连契约都还没有。我在驱动上直接加了两个方法，把异步任务的创建和轮询封装好了。
02
装起来，两分钟
环境要求是 PHP 8.4、Laravel 12 以上，外加 laravel/ai 0.10.3。
然后一行命令。
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'), // 语音、图像、视频走百炼原生接口 'api_url' => env('QWEN_API_URL', 'https://dashscope.aliyuncs.com/api/v1'), ], ],
这里有两个 URL，它们不是一回事。
url 走 OpenAI 兼容接口，管文本和向量。api_url 走百炼原生接口，管语音、图像、视频。
为什么要拆开。因为百炼的多模态能力不在兼容模式里，必须调原生端点。填错一个，多模态就全军覆没。
最后在 .env 里填上百炼控制台拿的 API Key，收工。想让千问当默认提供方，加一行 AI_DEFAULT_PROVIDER=qwen 就行。
03
让应用开口说话
文本和向量没什么可讲的，官方文档怎么用就怎么用，provider 换成 qwen 完事。
真正补的课，是多模态这三样。先看语音合成，接的是 Qwen3-TTS。
use Laravel\Ai\Ai; $audio = Ai::audioProvider('qwen')->audio('你好，欢迎使用通义千问。'); // 直接存到存储盘 $audio->store('greeting.wav', 'public');
音色上有个贴心的设计。SDK 里的占位音色 default-female 和 default-male，会自动映射到配置里的默认女声 Cherry 和默认男声 Ethan。想换音色，直接传千问的音色名，比如 Serena。
还有个坑提前说了。Qwen3-TTS 不支持 OpenAI 的 instructions 参数，情绪和语气要靠音色和文本本身控制，传了也会被忽略。
非流式响应里 Base64 音频和 24 小时有效的 URL 都有，驱动优先用 Base64，省一次下载。
04
一句话，一张图
图像这块接的是 Qwen Image，生成和编辑都支持。
$image = Ai::imageProvider('qwen')->image( '一只在草地上奔跑的柴犬，阳光明媚，摄影风格', size: '3:2', ); $image->store('shiba.png', 'public');
尺寸支持 1:1、2:3、3:2、16:9、9:16 这些比例，也支持直接写像素。不显式指定的话，quality 参数会映射成分辨率档位，low 是 1024，medium 和 high 是 2048。
改图也简单，把参考图传进去就行。远端 URL、本地文件、存储盘文件、Base64，四种都认。
use Laravel\Ai\Files\RemoteImage; $image = Ai::imageProvider('qwen')->image( '把背景换成海边', [new RemoteImage('https://example.com/ref.png')], );
远端图直接透传 URL，本地文件自动转成 Base64 Data URI 再提交。这个转换是驱动默默干的，调用方无感。
05
视频生成，也安排上了
视频这块得多说两句。
百炼的视频生成是异步任务。提交，拿 task_id，然后轮询，整个过程可能要几分钟。
laravel/ai 目前还没有 VideoProvider 契约，所以我把两个方法直接挂在了驱动实例上。
$provider = Ai::instance('qwen'); // 创建文生视频任务 $task = $provider->createVideoTask('一只猫在草地上奔跑，镜头缓慢推进', [ 'duration' => 5, // 时长，秒 'resolution' => '1080P', // 480P / 720P / 1080P 'ratio' => '16:9', // 画幅比例 ]); // 轮询任务结果 $result = $provider->getVideoResult($task['task_id']); if ($result['task_status'] === 'SUCCEEDED') { $videoUrl = $result['video_url']; }
文生视频传一段描述就行。图生视频支持首帧和尾帧，万相 3.0 用 media 数组传。
时长、分辨率、画幅、水印、提示词智能改写，都在 options 里配。
有一件事必须加粗提醒。
**任务 ID 和生成出来的视频 URL，有效期都只有 24 小时。**跑完任务记得及时下载。别问我怎么知道的。
06
藏在细节里的功夫
这个包不大，但细节没少花心思。
异常处理沿用 Laravel AI 的官方异常体系。限流、余额不足、服务过载，各有各的异常类，调用处统一捕获，不用为千问单写一套。
图像的智能改写和水印开关收进了配置项，不用每次调用都传。所有配置都能用环境变量覆盖，多环境部署不用改代码。
新加坡等海外地域，把两个 URL 换成对应地域的地址就能用。
07
最后想说的话
说点题外话。
这两年总有人说 PHP 老了。可我看到的 Laravel 社区，动作一直没停，连官方 AI 框架都安排上了。
语言哪有什么新旧。
大模型时代，拼的是生态里有没有人把路修通。
这个包，就是我修的一小段路。
MIT 协议，随便用。觉得有用，点个 Star。有想法，提 Issue。想一起修，PR 随时欢迎。
GitHub 搜 laravel-ai-qwen，第一个就是。
包地址 Packagist 搜 larva/laravel-ai-qwen
源码地址 github.com/larva-cool/laravel-ai-qwen
文档在 README，安装到跑通只要两分钟
