一、千问大模型API概述
阿里云通义千问是阿里巴巴达摩院自主研发的大规模语言模型,提供文本生成、问答对话、代码编写、多模态理解等多种AI能力。千问API通过两种方式对外开放:DashScope SDK和OpenAI兼容接口。DashScope是阿里云官方提供的模型服务SDK,目前已支持Python和Java等语言;OpenAI兼容接口则让开发者可以使用熟悉的OpenAI SDK调用千问模型。这种双轨并行的设计极大降低了不同技术栈开发者的接入门槛。
千问系列提供了多个模型规格供开发者选择:qwen-max是全能型模型,支持1M token上下文,中英文混合处理能力强,适用于复杂问答和通用对话;qwen-plus性价比高、响应速度快,适合日常客服和内容生成场景;qwen-long专为超长上下文设计,支持高达1000万tokens的输入,约合1500万字或1.5万页文档;qwen-vl支持多模态(文本+图像),可用于图像理解和图文生成。开发者应根据实际业务场景选择合适的模型版本,在性能与成本之间取得平衡。
需要先登录阿里云控制台,点击:阿里云控制台
二、准备工作:开通服务与获取API Key
无论使用哪种编程语言,接入千问API的第一步都是完成账号开通和密钥获取。整个过程仅需几分钟:
首先访问阿里云百炼控制台,完成注册或登录流程。然后在左侧导航栏选择「API密钥管理」,点击「创建密钥」按钮生成新的API Key。生成的密钥格式类似sk-xxxxxxxxxxxxxx,这是调用千问API的唯一凭证,务必妥善保存。
安全方面需要特别注意:API Key是访问服务的凭证,切勿直接硬编码在客户端代码中,建议通过环境变量或加密存储方式管理。在Linux/macOS系统中可通过 export DASHSCOPE_API_KEY="sk-xxx" 设置环境变量,在Windows系统中可通过 set DASHSCOPE_API_KEY=sk-xxx 设置。
验证环境是否就绪也很关键。对于PHP开发者,可通过 php -r "var_dump(extension_loaded('curl'));" 命令检查cURL扩展是否可用。Python开发者则需确保Python版本不低于3.7。Java开发者需要注意SDK版本不低于2.20.9。
三、PHP接入千问API
PHP生态中目前没有官方维护的DashScope SDK,因此PHP开发者需要通过直连DashScope REST API的方式进行调用。核心思路是使用cURL发送HTTP POST请求,在请求头中携带 Authorization: Bearer {API_Key},请求体为符合千问API规范的JSON数据。
以下是一个完整的PHP封装类示例,展示了如何调用通义千问生成文本:
<?php class TongyiQwenClient { private $apiKey; private $apiUrl = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation'; public function __construct($apiKey) { $this->apiKey = $apiKey; } public function generateText($prompt, $model = 'qwen-plus') { $data = [ 'model' => $model, 'input' => [ 'messages' => [ ['role' => 'user', 'content' => $prompt] ] ], 'parameters' => new stdClass() ]; $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => $this->apiUrl, CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $this->apiKey, 'Content-Type: application/json' ], CURLOPT_TIMEOUT => 30 ]); $response = curl_exec($curl); $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($httpCode !== 200) { return ['error' => "HTTP错误: $httpCode", 'response' => $response]; } $result = json_decode($response, true); $content = $result['output']['text'] ?? $result['output']['choices'][0]['message']['content'] ?? null; return ['content' => $content, 'raw' => $result]; } } // 使用示例 $apiKey = getenv('DASHSCOPE_API_KEY'); $client = new TongyiQwenClient($apiKey); $result = $client->generateText('请介绍一下量子计算的基本原理', 'qwen-max'); echo $result['content'] ?? '调用失败'; ?>
对于流式输出场景,可以设置 CURLOPT_WRITEFUNCTION 回调函数逐块处理响应数据。此外,社区中也有一些第三方PHP包可供选择,例如 azozzalfiras/qwen-ai,可通过 composer require azozzalfiras/qwen-ai 安装,它封装了文本生成、图像生成、视频生成等能力。
PHP环境要求方面,需要确保PHP版本不低于7.4(推荐8.0+),并启用cURL扩展。
四、Java接入千问API
Java开发者可以通过DashScope官方SDK快速集成千问能力。在Maven项目中,需要在pom.xml中添加DashScope依赖,版本不低于2.20.9。
方式一:使用DashScope SDK
import com.alibaba.dashscope.aigc.generation.Generation; import com.alibaba.dashscope.aigc.generation.GenerationParam; import com.alibaba.dashscope.common.Message; import com.alibaba.dashscope.common.Role; import com.alibaba.dashscope.exception.ApiException; import com.alibaba.dashscope.exception.NoApiKeyException; import com.alibaba.dashscope.exception.UploadFileException; import com.alibaba.dashscope.utils.Constants; public class QwenJavaDemo { public static void main(String[] args) { String apiKey = System.getenv("DASHSCOPE_API_KEY"); Generation gen = new Generation(); Message userMsg = Message.builder() .role(Role.USER.getValue()) .content("请用Java实现一个快速排序算法") .build(); GenerationParam param = GenerationParam.builder() .apiKey(apiKey) .model("qwen-plus") .messages(java.util.Arrays.asList(userMsg)) .resultFormat(GenerationParam.ResultFormat.MESSAGE) .build(); try { GenerationResult result = gen.call(param); System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent()); } catch (ApiException | NoApiKeyException | UploadFileException e) { System.err.println("调用失败: " + e.getMessage()); } } }
方式二:使用OpenAI兼容模式
import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.chat.completions.ChatCompletion; import com.openai.models.chat.completions.ChatCompletionCreateParams; public class QwenOpenAIJava { public static void main(String[] args) { OpenAIClient client = OpenAIOkHttpClient.builder() .apiKey(System.getenv("DASHSCOPE_API_KEY")) .baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1") .build(); ChatCompletionCreateParams params = ChatCompletionCreateParams.builder() .addUserMessage("解释一下什么是RESTful API") .model("qwen-plus") .build(); ChatCompletion completion = client.chat().completions().create(params); System.out.println(completion.choices().get(0).message().content().get()); } }
对于实时语音识别等高级场景,DashScope Java SDK还提供了WebSocket支持。需要注意的是,新加坡地域的用户应及时从旧版域名迁移至新的业务空间专属域名。
在Maven项目中添加依赖的配置如下:
<dependency> <groupId>com.alibaba</groupId> <artifactId>dashscope-sdk-java</artifactId> <version>2.21.12</version> </dependency>
五、Python接入千问API
Python是目前对接千问API最成熟的语言之一,官方提供了完整的DashScope SDK支持。安装方式极为简单:pip install dashscope。此外,由于千问API兼容OpenAI接口协议,开发者也可以直接使用 pip install openai 安装OpenAI SDK进行调用。
方式一:使用DashScope SDK
import dashscope from dashscope import Generation import os dashscope.api_key = os.getenv('DASHSCOPE_API_KEY') response = Generation.call( model='qwen-turbo', prompt='请写一首关于春天的五言诗' ) if response.status_code == 200: print(response.output.text) else: print(f'调用失败: {response.code} - {response.message}')
方式二:使用OpenAI兼容模式
from openai import OpenAI import os client = OpenAI( api_key=os.getenv('DASHSCOPE_API_KEY'), base_url='https://dashscope.aliyuncs.com/compatible-mode/v1' ) completion = client.chat.completions.create( model='qwen-plus', messages=[ {'role': 'system', 'content': '你是一位专业的编程助手'}, {'role': 'user', 'content': '如何用Python实现一个简单的Web服务器?'} ], temperature=0.7 ) print(completion.choices[0].message.content)
多轮对话是Python接入的常见场景,只需在messages列表中维护完整的对话历史即可。对于需要联网搜索的场景,可以通过 extra_body 参数传入 enable_search 选项。Python SDK还支持流式输出,通过设置 stream=True 并迭代处理响应块,可以实现打字机效果的实时响应。
以下是一个多轮对话的示例:
def chat_with_qwen(messages): try: completion = client.chat.completions.create( model="qwen-turbo", messages=messages ) return completion.choices[0].message.content except Exception as e: print(f"调用 API 失败: {e}") return None
六、Go接入千问API
Go语言的官方SDK支持相对有限,但开发者可以通过OpenAI兼容模式顺利调用千问模型。Go社区已有开发者基于OpenAI SDK封装了千问调用示例。
以下是一个完整的Go调用示例,使用OpenAI兼容接口:
package main import ( "context" "fmt" "os" "github.com/openai/openai-go" "github.com/openai/openai-go/option" ) func main() { apiKey := os.Getenv("DASHSCOPE_API_KEY") if apiKey == "" { panic("请设置DASHSCOPE_API_KEY环境变量") } client := openai.NewClient( option.WithAPIKey(apiKey), option.WithBaseURL("https://dashscope.aliyuncs.com/compatible-mode/v1"), ) chat, err := client.Chat.Completions.New( context.Background(), openai.ChatCompletionNewParams{ Model: openai.String("qwen-plus"), Messages: []openai.ChatCompletionMessageParamUnion{ openai.UserMessage("用Go语言实现一个并发安全的计数器"), }, Temperature: openai.Float(0.8), }, ) if err != nil { panic(err) } fmt.Println(chat.Choices[0].Message.Content) }
对于更复杂的场景,如Assistant构建、会话管理、消息与运行任务等,可以参考社区开发者提供的示例项目。这些示例涵盖了助手创建、会话创建、消息创建、运行任务执行等完整流程。虽然官方未提供完善的Go语言示例,但实际使用中OpenAI兼容模式完全能够支持千问的各类功能。
七、.NET(C#)接入千问API
.NET开发者可以通过HTTP客户端直接调用千问API,也可以使用OpenAI的.NET SDK通过兼容模式接入。由于千问API遵循OpenAI Chat Completion规范,.NET生态中的成熟封装模式可以直接复用。
以下是一个完整的C#封装示例:
using System.Text.Json; using System.Text.Json.Serialization; namespace QwenClient.Models { public class ChatMessage { [JsonPropertyName("role")] public string Role { get; set; } = "user"; [JsonPropertyName("content")] public string Content { get; set; } = string.Empty; } public class ChatCompletionRequest { [JsonPropertyName("model")] public string Model { get; set; } = "qwen-plus"; [JsonPropertyName("messages")] public List<ChatMessage> Messages { get; set; } = new(); [JsonPropertyName("temperature")] public double? Temperature { get; set; } [JsonPropertyName("stream")] public bool? Stream { get; set; } } public class ChatCompletionResponse { [JsonPropertyName("choices")] public List<Choice> Choices { get; set; } = new(); } public class Choice { [JsonPropertyName("message")] public ChatMessage Message { get; set; } = new(); } } public class QwenClient { private readonly HttpClient _httpClient; private readonly string _apiKey; private const string BaseUrl = "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"; public QwenClient(string apiKey) { _apiKey = apiKey; _httpClient = new HttpClient(); _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {_apiKey}"); } public async Task<string> ChatAsync(string prompt, string model = "qwen-plus") { var request = new ChatCompletionRequest { Model = model, Messages = new List<ChatMessage> { new() { Role = "user", Content = prompt } }, Temperature = 0.7 }; var json = JsonSerializer.Serialize(request); var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json"); var response = await _httpClient.PostAsync(BaseUrl, content); var responseJson = await response.Content.ReadAsStringAsync(); if (!response.IsSuccessStatusCode) { throw new Exception($"API调用失败: {response.StatusCode} - {responseJson}"); } var result = JsonSerializer.Deserialize<ChatCompletionResponse>(responseJson); return result?.Choices?.FirstOrDefault()?.Message?.Content ?? string.Empty; } } // 使用示例 var client = new QwenClient(Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY")); var reply = await client.ChatAsync("C#中async/await的工作原理是什么?"); Console.WriteLine(reply);
对于需要流式响应的场景,可以使用HttpClient的 StreamAsync 方法逐行解析Server-Sent Events(SSE)数据。此外,通过 Microsoft.Extensions.AI 等抽象库,也可以统一接入千问模型。
八、进阶技巧与最佳实践
8.1 模型选型策略
不同模型在性能、成本和能力上各有侧重。qwen-max适合对推理质量要求高的复杂场景;qwen-plus在性价比上有优势,适合大规模生产环境;qwen-long专攻超长文档处理;qwen-vl支持图文多模态。建议在生产环境中优先选用有LTS标识的稳定版本,避免使用实验性模型。
8.2 参数调优
temperature参数控制回答的随机性,取值范围0.0到1.0,值越高回答越多样化,值越低越保守确定。对于需要精确答案的场景建议使用较低值(如0.1-0.3),对于创意类任务可以使用较高值(如0.8-0.9)。top_p参数也常用于控制生成多样性,通常与temperature配合使用。
8.3 错误处理
API调用可能遇到多种错误,包括认证失败(401)、请求限流(429)、服务端错误(5xx)等。建议实现指数退避重试机制,并在代码中妥善处理各类异常。对于长时间运行的任务,应设置合理的超时时间(建议30-60秒)。
8.4 安全实践
API Key应始终通过环境变量或密钥管理服务读取,严禁硬编码在代码仓库中。生产环境建议使用RAM子账号进行最小权限授权,避免主账号密钥泄露风险。对于敏感业务场景,可启用内容审核机制对模型输出进行过滤。
8.5 成本优化
千问API按Token计费,新用户通常享有免费额度。优化成本的核心策略包括:选择合适的模型规格(qwen-plus性价比优于qwen-max)、控制输入输出长度、使用流式输出改善用户体验、对高频请求实施缓存。定期监控API调用量和费用,及时发现异常调用。
九、常见问题解答
问1:PHP有没有官方的DashScope SDK?
目前阿里云官方未提供PHP版本的DashScope SDK,PHP开发者需要通过cURL直接调用DashScope REST API。社区中有一些第三方封装包可供参考,但建议在生产环境中自行封装以保持可控性。
问2:Java接入时SDK版本有什么要求?
DashScope Java SDK版本需要不低于2.20.9。建议使用Maven或Gradle管理依赖,定期更新到最新稳定版本以获取新功能和Bug修复。
问3:Python中如何使用流式输出?
在调用时设置 stream=True 参数,然后迭代处理响应流。DashScope SDK和OpenAI兼容模式均支持流式输出,可以逐块接收模型生成的文本,实现打字机效果。
问4:Go语言调用千问有哪些注意事项?
官方未提供完善的Go语言示例,但OpenAI兼容模式完全可用。建议使用 openai-go 等社区SDK,配置 base_url 指向千问的兼容接口地址。对于Assistant等高级功能,可以参考社区开发者分享的示例项目。
问5:.NET中如何实现多轮对话?
多轮对话的核心是在每次请求的 messages 列表中携带完整的对话历史,包括 user 和 assistant 的交替消息。建议在服务端维护会话状态,将历史消息持久化存储以便跨请求复用。
问6:如何在不同语言之间共享API Key管理策略?
推荐统一使用环境变量 DASHSCOPE_API_KEY 存储API Key。在CI/CD流水线中通过密钥管理服务注入,在容器化部署时通过Secret挂载。这样无论使用哪种编程语言,都能保持一致的密钥管理方式,降低泄露风险。