Laravel 集成通义千问：从 API 调用到 Agent 模式的最佳实践

2026-07-17 09:08顾国敏

为什么选择通义千问？

在国产大模型中，千问的优势主要体现在几个方面：模型矩阵完整，从轻量的 qwen-turbo 到推理能力更强的 qwen-max，再到专为代码场景优化的 qwen-coder-plus，可以匹配不同的业务需求；API 兼容 OpenAI 格式，这意味着我们可以复用 Laravel 生态中已有的工具链，而不必为每个模型单独写一套驱动；性价比方面，千问系列模型也提供了不错的免费额度。

方案选型：两条主流路径

目前 Laravel 集成千问主要有两种技术路线，各有侧重：

路径一：使用 Laravel AI SDK（官方推荐）

Laravel 官方推出的 AI SDK 提供了一套统一的 AI 能力抽象层。它的核心设计理念是 Agent（代理）模式——将 AI 行为封装成独立的类，而非散落在控制器里的 API 调用。这样做的好处是职责清晰、可复用性强，也方便后续切换底层模型。

关键在于，千问的 API 与 OpenAI 格式兼容，我们只需要修改 base_url 和 api_key 就能接入。

路径二：使用社区 AI 聚合包

像 phpais/ai-plugin 或 wolfcode/php-ai 这类社区包，通过统一的工厂方法对接多个大模型。如果项目同时需要接入千问、DeepSeek 或混元，这类方案能减少重复配置。但如果只需要千问，Laravel AI SDK 的官方支持度和 Agent 模式带来的工程收益会更高。

综合考虑，下文以 Laravel AI SDK 方案为主进行详解。

实战：接入千问的完整步骤

第一步：安装与配置

通过 Composer 安装 Laravel AI SDK，并发布配置文件：

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

然后获取阿里云百炼平台的 API Key（进入控制台「API-KEY 管理」创建），在 .env 中配置千问相关变量：

QWEN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

在 config/ai.php 中添加千问的 provider 配置。核心是将 driver 设为 openai，利用其兼容性：

'providers' => [
    'qwen' => [
        'driver' => 'openai',
        'key'    => env('QWEN_API_KEY'),
        'url'    => env('QWEN_BASE_URL'),
    ],
],

第二步：创建你的第一个 Agent

Agent 是 Laravel AI SDK 的核心概念。以翻译场景为例，我们定义一个 MyTranslationAgent 类，将翻译指令、目标语言和风格封装其中：

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class MyTranslationAgent implements Agent
{
    use Promptable;

    public string $provider = 'qwen';
    public string $model = 'qwen-plus';  // 均衡性能

    public function __construct(
        protected string $targetLang = 'English',
        protected string $style = 'formal'
    ) {}

    public function instructions(): string
    {
        return <<<PROMPT
你是一位精通中英文的专业翻译专家。
请将用户提供的文本翻译为 {$this->targetLang}。
风格要求：{$this->style}
只输出译文，不添加任何解释。
PROMPT;
    }
}

第三步：在服务层调用

通过服务类调用 Agent，业务逻辑与 AI 行为解耦：

<?php

namespace App\Services;

use App\Ai\Agents\MyTranslationAgent;

class TranslationAgentService
{
    public function translate(string $text, string $targetLang = 'English'): string
    {
        $agent = new MyTranslationAgent($targetLang);
        return $agent->prompt($text, provider: $agent->provider, model: $agent->model);
    }
}

第四步：在控制器中使用

控制器只需调用服务层，保持轻量：

<?php

namespace App\Http\Controllers;

use App\Services\TranslationAgentService;
use Illuminate\Http\Request;

class TranslationController extends Controller
{
    public function translate(Request $request, TranslationAgentService $service)
    {
        $request->validate(['text' => 'required|string|max:5000']);
        
        $translation = $service->translate($request->text, 'Chinese');
        
        return response()->json(['success' => true, 'translation' => $translation]);
    }
}

进阶实践：流式输出与模型选型

流式输出（SSE）

对于聊天或长文本生成场景，流式输出能显著提升用户体验。Laravel AI SDK 支持通过 stream() 方法实现，前端配合 SSE 即可接收逐字响应：

public function stream(Request $request)
{
    return response()->stream(function () use ($request) {
        $stream = AI::provider('qwen')
            ->model('qwen-turbo')
            ->chat()
            ->stream([['role' => 'user', 'content' => $request->message]]);

        foreach ($stream as $chunk) {
            echo "data: " . json_encode(['content' => $chunk]) . "\n\n";
            ob_flush();
            flush();
        }
        echo "data: [DONE]\n\n";
    }, 200, [
        'Content-Type' => 'text/event-stream',
        'Cache-Control' => 'no-cache',
    ]);
}

模型选型参考

千问提供多个模型版本，可根据场景按需选择：

模型	适用场景
`qwen-turbo`	高并发、简单问答，速度最快且成本最低
`qwen-plus`	日常对话、内容生成，性能均衡
`qwen-max`	复杂推理、代码生成，推理能力最强
`qwen-coder-plus`	代码补全、代码审查等代码专用场景

常见问题与调优建议

超时设置：复杂推理任务可能耗时较长，需在请求层设置合理的超时时间。社区实践中建议对推理模型设置 setTimeLimit(0) 以避免中断。

API Key 安全：务必通过 .env 管理敏感信息，切勿硬编码在代码中或提交到版本控制。

成本控制：考虑在业务层对高频调用做缓存（如相同问题的翻译结果），或对用户的单次请求 Token 数量做上限控制。

Agent 模式的价值：将 AI 能力抽象为 Agent 后，未来若要切换模型（如从千问切到 DeepSeek），只需修改 Agent 类中的 $provider 和 $model 属性，业务层完全感知不到变化，这正是解耦带来的可维护性收益。

总结

在 Laravel 中集成通义千问，通过 Laravel AI SDK 的 Agent 模式，我们可以将 AI 能力以一种整洁、可扩展的方式融入项目。核心思路是利用千问 API 对 OpenAI 格式的兼容性，通过配置驱动完成接入，再以 Agent 封装具体的 AI 行为，最终实现业务层与 AI 层的解耦。这套方案既能快速落地，也为未来的模型迭代留足了空间。

曝光252浏览20