1. 前置准备：开通服务与获取凭证
在正式开始对接阿里千问大模型API之前，需要完成账号注册、服务开通和API Key创建等准备工作。这些步骤是后续所有语言SDK调用的基础，无论使用哪种编程语言，流程完全一致。
首先需要注册阿里云账号并完成实名认证，这是开通任何付费服务的前置条件。完成认证后，进入阿里云百炼大模型服务平台，阅读并同意服务协议即可自动开通百炼服务。需要先登录阿里云控制台，点击：阿里云控制台。
API Key是调用千问API的唯一身份凭证，创建步骤为：在百炼控制台左侧导航栏选择“密钥管理” > “API-Key”页签，点击“创建API-KEY”即可生成。创建后请妥善保管，建议将其配置到系统环境变量中而非硬编码在代码里，以降低泄露风险。具体配置方式因操作系统而异：在Linux/macOS中可通过export DASHSCOPE_API_KEY='your-api-key'设置，Windows中可通过set DASHSCOPE_API_KEY=your-api-key设置。
如果使用华北2（北京）、新加坡、德国（法兰克福）或中国香港地域的模型服务，还需要获取业务空间ID（WorkspaceId），该ID需在Base URL中传入。
2. 调用方式概述：DashScope SDK与OpenAI兼容接口
阿里云百炼平台为开发者提供了两种调用千问大模型API的方式：DashScope原生SDK和OpenAI兼容接口。
DashScope是阿里云官方推出的大模型服务SDK，目前官方支持Python和Java两种语言，其他语言可通过HTTP协议直接调用DashScope API。其请求地址根据地域和模型类型有所不同：纯文本模型的RESTful API地址为https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation，多模态模型则为https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。
OpenAI兼容接口是另一种便捷的接入方式，通过设置base_url为https://dashscope.aliyuncs.com/compatible-mode/v1，即可使用各语言中已有的OpenAI SDK客户端来调用千问模型。这种方式对于已经熟悉OpenAI API生态的开发者尤为友好，代码迁移成本极低。本文后续将针对每种语言分别展示两种调用方式的具体实现。
3. 模型选型指南
通义千问提供了多个模型版本以适应不同的应用场景：
- qwen-turbo：响应速度快、成本较低，适用于对话、问答等轻量级实时交互任务。
- qwen-plus：性能均衡，适合内容创作、文本总结、写作辅助等中等复杂度的任务。
- qwen-max：推理能力最强，适用于深度逻辑分析、长文本生成、复杂代码编写等场景。
- qwen-long：专为超长上下文设计，支持高达1000万tokens的输入，约合1500万字或1.5万页文档。
- qwen-vl系列：多模态模型，支持图像理解与图文混合问答。
开发者应根据实际业务需求、响应速度要求和成本预算综合选择合适的模型版本。
4. PHP对接千问大模型API
4.1 环境要求
PHP版本需≥7.4（推荐8.0+），并确保已启用cURL扩展。
4.2 通过HTTP直接调用DashScope API
由于PHP暂无官方DashScope SDK，推荐直接通过cURL发送HTTP请求调用API。以下是完整的单轮对话示例：
<?php\n\nfunction callQwen($prompt, $model = 'qwen-plus') {\n $apiKey = getenv('DASHSCOPE_API_KEY');\n if (empty($apiKey)) {\n throw new Exception('请设置DASHSCOPE_API_KEY环境变量');\n }\n\n $url = 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation';\n\n $data = [\n 'model' => $model,\n 'input' => [\n 'messages' => [\n ['role' => 'user', 'content' => $prompt]\n ]\n ],\n 'parameters' => [\n 'result_format' => 'message',\n 'temperature' => 0.8\n ]\n ];\n\n $ch = curl_init();\n curl_setopt_array($ch, [\n CURLOPT_URL => $url,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_POST => true,\n CURLOPT_POSTFIELDS => json_encode($data),\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . $apiKey,\n 'Content-Type: application/json'\n ],\n CURLOPT_TIMEOUT => 30\n ]);\n\n $response = curl_exec($ch);\n $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\n curl_close($ch);\n\n if ($httpCode !== 200) {\n throw new Exception('API调用失败，HTTP状态码：' . $httpCode);\n }\n\n $result = json_decode($response, true);\n return $result['output']['choices'][0]['message']['content'] ?? '未获取到有效响应';\n}\n\n// 调用示例\ntry {\n $answer = callQwen('请用一句话介绍什么是大语言模型');\n echo $answer;\n} catch (Exception $e) {\n echo '错误：' . $e->getMessage();\n}\n?>
对于多轮对话场景，只需在messages数组中依次追加历史对话记录即可，每条消息包含role（system/user/assistant）和content两个字段。
4.3 通过OpenAI兼容接口调用
PHP开发者也可以使用openai-php/client等开源库，通过OpenAI兼容接口调用千问：
use OpenAI\Client;\n\n$client = OpenAI::factory()\n ->withApiKey(getenv('DASHSCOPE_API_KEY'))\n ->withBaseUri('https://dashscope.aliyuncs.com/compatible-mode/v1')\n ->make();\n\n$response = $client->chat()->create([\n 'model' => 'qwen-plus',\n 'messages' => [\n ['role' => 'user', 'content' => '你好，请介绍一下自己']\n ],\n 'temperature' => 0.7\n]);\n\necho $response->choices[0]->message->content;
5. Java对接千问大模型API
5.1 环境与依赖
Java开发者需使用DashScope Java SDK，版本要求不低于2.12.0，推荐使用最新版本。在Maven项目中添加以下依赖：
<dependency>\n <groupId>com.alibaba</groupId>\n <artifactId>dashscope-sdk-java</artifactId>\n <version>2.22.15</version>\n</dependency>
5.2 通过DashScope SDK调用
SDK会自动从环境变量DASHSCOPE_API_KEY中读取API Key，无需在代码中显式配置。以下为完整调用示例：
import com.alibaba.dashscope.aigc.generation.Generation;\nimport com.alibaba.dashscope.aigc.generation.GenerationParam;\nimport com.alibaba.dashscope.aigc.generation.GenerationResult;\nimport com.alibaba.dashscope.common.Message;\nimport com.alibaba.dashscope.common.MessageManager;\nimport com.alibaba.dashscope.common.Role;\nimport com.alibaba.dashscope.exception.ApiException;\nimport com.alibaba.dashscope.exception.NoApiKeyException;\n\npublic class QwenExample {\n public static void main(String[] args) {\n try {\n Generation gen = new Generation();\n MessageManager msgManager = new MessageManager();\n msgManager.add(Message.builder()\n .role(Role.USER.getValue())\n .content(\"请用Java写一个快速排序算法\")\n .build());\n\n GenerationParam param = GenerationParam.builder()\n .model(\"qwen-plus\")\n .messages(msgManager.get())\n .resultFormat(GenerationParam.ResultFormat.MESSAGE)\n .temperature(0.8f)\n .build();\n\n GenerationResult result = gen.call(param);\n System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent());\n } catch (ApiException | NoApiKeyException e) {\n System.err.println(\"调用失败：\" + e.getMessage());\n }\n }\n}
5.3 多轮对话与流式输出
多轮对话只需在每次请求时将历史消息添加到MessageManager中即可。如需流式输出，可在GenerationParam中设置.incrementalOutput(true)，并通过回调函数处理流式返回的片段。
5.4 配置WorkspaceId
如果使用新加坡、德国（法兰克福）或中国香港地域，需要在初始化时设置Base URL：
import com.alibaba.dashscope.utils.Constants;\n\nConstants.baseHttpApiUrl = \"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1\";
将{WorkspaceId}替换为实际的业务空间ID。
6. .NET（C#）对接千问大模型API
6.1 调用方式概述
阿里云官方暂未提供.NET平台的DashScope SDK，但开发者可以通过以下两种方式实现对接：使用开源社区提供的.NET SDK（如Sdcb.DashScope），或直接通过HttpClient调用RESTful API。本文重点介绍后者，因为它不依赖第三方库，通用性最强。
6.2 定义数据模型
首先定义请求和响应的C#类：
using System.Text.Json.Serialization;\n\npublic class ChatMessage\n{\n [JsonPropertyName(\"role\")]\n public string Role { get; set; } = \"user\";\n\n [JsonPropertyName(\"content\")]\n public string Content { get; set; } = string.Empty;\n}\n\npublic class ChatCompletionRequest\n{\n [JsonPropertyName(\"model\")]\n public string Model { get; set; } = \"qwen-plus\";\n\n [JsonPropertyName(\"input\")]\n public InputData Input { get; set; } = new();\n\n [JsonPropertyName(\"parameters\")]\n public Parameters Params { get; set; } = new();\n}\n\npublic class InputData\n{\n [JsonPropertyName(\"messages\")]\n public List<ChatMessage> Messages { get; set; } = new();\n}\n\npublic class Parameters\n{\n [JsonPropertyName(\"result_format\")]\n public string ResultFormat { get; set; } = \"message\";\n\n [JsonPropertyName(\"temperature\")]\n public float Temperature { get; set; } = 0.8f;\n}
6.3 封装HTTP调用客户端
using System.Text;\nusing System.Text.Json;\n\npublic class QwenClient\n{\n private readonly HttpClient _httpClient;\n private readonly string _apiKey;\n private const string BaseUrl = \"https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation\";\n\n public QwenClient()\n {\n _apiKey = Environment.GetEnvironmentVariable(\"DASHSCOPE_API_KEY\")\n ?? throw new InvalidOperationException(\"请设置DASHSCOPE_API_KEY环境变量\");\n _httpClient = new HttpClient();\n _httpClient.DefaultRequestHeaders.Add(\"Authorization\", $\"Bearer {_apiKey}\");\n }\n\n public async Task<string> ChatAsync(string prompt, string model = \"qwen-plus\")\n {\n var request = new ChatCompletionRequest\n {\n Model = model,\n Input = new InputData\n {\n Messages = new List<ChatMessage>\n {\n new() { Role = \"user\", Content = prompt }\n }\n },\n Params = new Parameters { Temperature = 0.8f }\n };\n\n var json = JsonSerializer.Serialize(request);\n var content = new StringContent(json, Encoding.UTF8, \"application/json\");\n\n var response = await _httpClient.PostAsync(BaseUrl, content);\n var responseJson = await response.Content.ReadAsStringAsync();\n\n if (!response.IsSuccessStatusCode)\n {\n throw new Exception($\"API调用失败：{response.StatusCode}\");\n }\n\n using var doc = JsonDocument.Parse(responseJson);\n var result = doc.RootElement\n .GetProperty(\"output\")\n .GetProperty(\"choices\")[0]\n .GetProperty(\"message\")\n .GetProperty(\"content\")\n .GetString();\n\n return result ?? \"未获取到有效响应\";\n }\n}
6.4 使用示例
var client = new QwenClient();\nstring answer = await client.ChatAsync(\"请用C#写一个异步读取文件的示例\");\nConsole.WriteLine(answer);
对于流式输出需求，可以使用HttpClient的GetStreamAsync方法配合StreamReader逐行读取服务器推送的Server-Sent Events（SSE）数据。
7. Python对接千问大模型API
7.1 环境与依赖
Python是目前AI应用开发中最常用的语言之一，阿里云提供了完整的Python SDK支持。安装以下依赖即可开始：
pip install -U dashscope openai
7.2 通过DashScope SDK调用
DashScope Python SDK会自动从环境变量DASHSCOPE_API_KEY读取API Key：
import os\nfrom dashscope import Generation\n\ndef call_qwen_dashscope(prompt: str, model: str = \"qwen-plus\") -> str:\n response = Generation.call(\n model=model,\n messages=[{\"role\": \"user\", \"content\": prompt}],\n result_format=\"message\",\n temperature=0.8\n )\n\n if response.status_code == 200:\n return response.output.choices[0].message.content\n else:\n raise Exception(f\"调用失败：{response.status_code} - {response.message}\")\n\n# 调用示例\nif __name__ == \"__main__\":\n result = call_qwen_dashscope(\"请介绍一下Python的异步编程\")\n print(result)
7.3 通过OpenAI兼容接口调用
使用OpenAI兼容接口是另一种简洁的方式：
import os\nfrom openai import OpenAI\n\nclient = OpenAI(\n api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\"\n)\n\ncompletion = client.chat.completions.create(\n model=\"qwen-plus\",\n messages=[{\"role\": \"user\", \"content\": \"你是谁？\"}],\n temperature=0.8\n)\n\nprint(completion.choices[0].message.content)
7.4 多轮对话实现
多轮对话通过维护一个消息列表来实现：
messages = [\n {\"role\": \"system\", \"content\": \"你是一个专业的编程助手\"}\n]\n\nwhile True:\n user_input = input(\"你：\")\n if user_input.lower() == \"exit\":\n break\n messages.append({\"role\": \"user\", \"content\": user_input})\n\n response = Generation.call(\n model=\"qwen-plus\",\n messages=messages,\n result_format=\"message\"\n )\n\n assistant_reply = response.output.choices[0].message.content\n print(f\"助手：{assistant_reply}\")\n messages.append({\"role\": \"assistant\", \"content\": assistant_reply})
7.5 流式输出
通过设置stream=True即可实现流式输出：
from dashscope import Generation\n\nresponses = Generation.call(\n model=\"qwen-plus\",\n messages=[{\"role\": \"user\", \"content\": \"写一篇200字的短文\"}],\n stream=True,\n result_format=\"message\"\n)\n\nfor response in responses:\n if response.output.choices[0].finish_reason != \"null\":\n print(response.output.choices[0].message.content, end=\"\", flush=True)
8. Go对接千问大模型API
8.1 调用方式概述
阿里云官方暂未提供Go语言的DashScope SDK，但开发者可以通过HTTP客户端直接调用DashScope RESTful API。Go语言的net/http标准库足以完成这一任务。
8.2 完整调用示例
package main\n\nimport (\n \"bytes\"\n \"encoding/json\"\n \"fmt\"\n \"io\"\n \"net/http\"\n \"os\"\n \"time\"\n)\n\nconst baseURL = \"https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation\"\n\ntype ChatMessage struct {\n Role string `json:\"role\"`\n Content string `json:\"content\"`\n}\n\ntype RequestInput struct {\n Messages []ChatMessage `json:\"messages\"`\n}\n\ntype RequestParams struct {\n ResultFormat string `json:\"result_format\"`\n Temperature float32 `json:\"temperature\"`\n}\n\ntype RequestBody struct {\n Model string `json:\"model\"`\n Input RequestInput `json:\"input\"`\n Parameters RequestParams `json:\"parameters\"`\n}\n\ntype ResponseBody struct {\n Output struct {\n Choices []struct {\n Message struct {\n Content string `json:\"content\"`\n } `json:\"message\"`\n } `json:\"choices\"`\n } `json:\"output\"`\n}\n\nfunc callQwen(prompt string, model string) (string, error) {\n apiKey := os.Getenv(\"DASHSCOPE_API_KEY\")\n if apiKey == \"\" {\n return \"\", fmt.Errorf(\"请设置DASHSCOPE_API_KEY环境变量\")\n }\n\n reqBody := RequestBody{\n Model: model,\n Input: RequestInput{\n Messages: []ChatMessage{\n {Role: \"user\", Content: prompt},\n },\n },\n Parameters: RequestParams{\n ResultFormat: \"message\",\n Temperature: 0.8,\n },\n }\n\n jsonData, err := json.Marshal(reqBody)\n if err != nil {\n return \"\", err\n }\n\n req, err := http.NewRequest(\"POST\", baseURL, bytes.NewBuffer(jsonData))\n if err != nil {\n return \"\", err\n }\n\n req.Header.Set(\"Authorization\", \"Bearer \"+apiKey)\n req.Header.Set(\"Content-Type\", \"application/json\")\n\n client := &http.Client{Timeout: 30 * time.Second}\n resp, err := client.Do(req)\n if err != nil {\n return \"\", err\n }\n defer resp.Body.Close()\n\n body, err := io.ReadAll(resp.Body)\n if err != nil {\n return \"\", err\n }\n\n if resp.StatusCode != http.StatusOK {\n return \"\", fmt.Errorf(\"API调用失败，状态码：%d，响应：%s\", resp.StatusCode, string(body))\n }\n\n var result ResponseBody\n if err := json.Unmarshal(body, &result); err != nil {\n return \"\", err\n }\n\n if len(result.Output.Choices) == 0 {\n return \"\", fmt.Errorf(\"未获取到有效响应\")\n }\n\n return result.Output.Choices[0].Message.Content, nil\n}\n\nfunc main() {\n answer, err := callQwen(\"请用Go语言写一个并发下载多个URL的示例\", \"qwen-plus\")\n if err != nil {\n fmt.Printf(\"错误：%v\\n\", err)\n return\n }\n fmt.Println(answer)\n}
8.3 流式输出实现
Go语言中实现流式输出需要处理Server-Sent Events（SSE）协议。在请求中设置stream: true参数，然后逐行读取响应体并解析data:前缀的事件数据。
9. 错误处理与重试策略
无论使用哪种语言，API调用都可能遇到网络超时、服务限流、参数错误等问题。建议在代码中实现以下错误处理机制：
- 网络超时：设置合理的超时时间（推荐30秒），超时后进行指数退避重试。
- 限流错误：当收到429状态码时，等待一段时间后重试，重试次数建议不超过3次。
- 参数错误：检查请求参数的合法性，特别是
model名称是否与所选地域匹配。 - 认证失败：检查API Key是否正确配置且未过期。
各语言SDK通常会在发生错误时抛出特定类型的异常，开发者应捕获这些异常并进行适当的降级处理。
10. 安全管理最佳实践
在生产环境中调用大模型API时，安全管理至关重要：
- 使用RAM子账号：避免使用主账号的AccessKey进行API调用，应创建RAM子账号并授予最小必要权限。
- 环境变量存储密钥：所有API Key应通过环境变量注入，严禁硬编码在代码仓库中。
- HTTPS加密传输：所有API请求均通过HTTPS协议传输，确保通信过程中的数据加密。
- 日志脱敏：在记录日志时，应对API Key、用户敏感信息等进行脱敏处理。
- 访问频率控制：在应用层实现请求频率控制，防止因突发流量导致费用激增或被限流。
11. 成本优化建议
通义千问API采用按量计费模式，主要计费项包括输入Token数、输出Token数和调用次数。以下几点有助于控制成本：
- 选择合适的模型：对于简单任务使用
qwen-turbo，复杂任务使用qwen-plus或qwen-max，避免“大材小用”。 - 控制输入长度：在发送请求前对用户输入进行适当截断或摘要，减少不必要的Token消耗。
- 缓存常见响应：对于高频的、答案相对固定的问题（如FAQ），可建立本地缓存避免重复调用。
- 利用免费额度：新用户注册后可获得一定量的免费Token额度，应优先使用免费额度进行测试和验证。
- 监控用量：在阿里云控制台定期查看API调用统计和费用明细，及时发现异常调用。
12. 总结
本文系统介绍了使用PHP、Java、.NET（C#）、Python、Go五种主流编程语言对接阿里千问大模型API的完整流程。从账号注册、服务开通、API Key获取等前置准备开始，详细阐述了DashScope原生SDK与OpenAI兼容接口两种调用方式，并为每种语言提供了完整的代码示例。无论您使用哪种技术栈，都能根据本文快速将千问大模型的强大能力集成到您的应用中。
在实际开发中，建议根据项目需求选择合适的调用方式：如果追求官方支持和稳定性，优先使用DashScope SDK（Python/Java）；如果希望保持代码在不同大模型平台间的可移植性，OpenAI兼容接口是更灵活的选择；对于官方未提供SDK的语言（PHP/.NET/Go），直接通过HTTP调用RESTful API同样高效可靠。
常见问题解答
问1：调用API时返回“Invalid API Key”错误，如何解决？
答：请检查环境变量DASHSCOPE_API_KEY是否正确设置且未过期。可以在阿里云百炼控制台的“密钥管理”页面重新生成新的API Key并替换。
问2：各语言SDK是否都支持流式输出？
答：Python的DashScope SDK原生支持流式输出（设置stream=True）；Java SDK也支持通过回调方式处理流式响应；其他语言通过HTTP直接调用时，可以处理SSE（Server-Sent Events）协议实现流式输出效果。
问3：多轮对话时如何传递历史消息？
答：所有调用方式均通过在messages数组中按顺序添加历史对话记录来实现多轮对话。每条记录包含role（system/user/assistant）和content字段，模型会根据完整的对话历史生成响应。
问4：WorkspaceId在什么情况下必须配置？
答：当使用华北2（北京）、新加坡、德国（法兰克福）或中国香港地域的模型服务时，需要在Base URL中传入WorkspaceId。使用默认地域（如dashscope.aliyuncs.com）则无需配置。
问5：qwen-turbo、qwen-plus和qwen-max之间如何选择？
答：qwen-turbo响应最快、成本最低，适合实时对话和简单问答；qwen-plus性能均衡，适合内容创作和中等复杂度任务；qwen-max推理能力最强，适合深度逻辑分析和长文本生成。建议根据任务复杂度逐级尝试，在满足效果的前提下选择成本更低的模型。
问6：如何监控API调用量和费用？
答：可以在阿里云控制台的“费用中心”查看账单明细，也可以在百炼控制台的“统计分析”页面查看API调用的详细统计信息，包括调用次数、Token消耗量等数据。
