通义千问API入门教程 - 阿里云开发者社区

在快速入门通义千问学习旅程中，本文为你提供从安装DashScope SDK到实际应用的全程指导。首先确保Python环境搭建完毕，通过pip轻松安装DashScope SDK。接着，注册并登录阿里云开发者社区，申请通义千问API服务并获取API-KEY，设置环境变量以备调用。本文详细介绍了两种API调用方式——通过messages和prompt，并提供了Python与Java示例代码。同时，深入分析了API调用的错误处理与响应结构解析。此外，还探讨了前端与后端集成的最佳实践，包括前端的AJAX或Fetch API调用与后端Flask框架的处理逻辑。最后，强调了API-KEY管理、错误码处理和性能优化的重要性，助你安全高效地运用通义千问API构建智能应用。

快速入门指南：使用通义千问API

安装DashScope SDK
首先，确保已安装Python环境，然后通过pip安装DashScope SDK：

pip install dashscope

开通服务并获取API-KEY
访问阿里云开发者社区，注册并申请通义千问API服务。注册后，登录到控制台，找到您的API-KEY并将其保存到环境变量DASHSCOPE_API_KEY中。

配置环境变量
在控制台中，您可以看到API-KEY如下：

DASHSCOPE_API_KEY=您的API-KEY

API使用方法
通义千问API支持通过messages调用和通过prompt调用两种方式。下面分别介绍这两种方法的使用。

1. 通过messages调用

messages方法适用于多轮对话场景，允许您构建对话历史并逐步生成回复。

from dashscope.nlp import TextGenerationClient

# 初始化客户端
client = TextGenerationClient()

# 生成回复
messages = [{"role": "user", "content": "你好，我想知道Python的基本语法。"}]
response = client.text_completion(model="qwen-turbo", max_tokens=200, messages=messages)
print(response)

2. 通过prompt调用

prompt方法适用于简单的一次性对话场景。

from dashscope.nlp import TextGenerationClient

# 初始化客户端
client = TextGenerationClient()

# 生成回复
prompt = "你好，我想知道Python的基本语法。"
response = client.text_completion(model="qwen-turbo", prompt=prompt)
print(response)

调用示例

Python示例：通过messages调用通义千问大模型提问

from dashscope.nlp import TextGenerationClient

client = TextGenerationClient()

messages = [{"role": "user", "content": "请解释什么是面向对象编程？"}]
response = client.text_completion(model="qwen-turbo", max_tokens=200, messages=messages)
print(response)

Java示例：通过messages调用通义千问大模型提问

import com.aliyun.nlp.pipeline.TextGenerationClient;
import com.aliyun.nlp.model.CompletionRequest;

public class CommAIExample {

    public static void main(String[] args) {
        TextGenerationClient client = TextGenerationClient.builder()
            .endpoint("https://nlp-api.aliyuncs.com")
            .accessKeyId("您的AccessKeyId")
            .accessKeySecret("您的AccessKeySecret")
            .build();

        CompletionRequest request = CompletionRequest.builder()
            .model("qwen-turbo")
            .prompt("请解释什么是面向对象编程？")
            .maxTokens(200)
            .build();

        CompletionResult result = client.completion(request);
        System.out.println(result);
    }
}

错误处理与API响应分析

Python与Java的差异

Python调用API时，错误信息通常直接在返回的字典中包含错误码和错误消息。Java调用API时，如果发生错误，会抛出异常，异常信息中包含错误码和错误消息。

API响应结构解析

API响应通常包括状态码、请求ID、错误码、错误信息、输出文本、完成原因以及输入/输出/总token数等元素。

使用API的前端与后端集成

前端集成示例：使用API调用获取响应

前端可以使用AJAX或Fetch API向后端API发起请求，并处理返回的数据。例如，使用JavaScript的Fetch API：

fetch('/api/ask-question', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-DASHSCOPE-API-KEY': '您的API-KEY'
    },
    body: JSON.stringify({ question: '请解释什么是面向对象编程？' })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

后端处理：处理API返回的数据并返回给前端

后端服务器需要解析前端发送的请求，调用API服务，并将响应数据返回给前端。使用Python Flask框架的示例：

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/ask-question', methods=['POST'])
def ask_question():
    api_key = request.headers.get('X-DASHSCOPE-API-KEY')
    question = request.json.get('question')

    if not api_key:
        return jsonify(error="API Key not provided"), 400

    try:
        response = call_dashscope_api(api_key, question)
    except Exception as e:
        return jsonify(error=str(e)), 500

    return jsonify(response), 200

def call_dashscope_api(api_key, question):
    # 这里添加调用DashScope API的逻辑
    # ...
    return response_data

if __name__ == '__main__':
    app.run(debug=True)

安全与最佳实践

• API-KEY管理：妥善保管API-KEY，避免将其泄露到不可信的环境中。
• 错误码管理：正确处理API返回的错误码与消息，根据错误码采取相应的应对措施。
• 性能优化：考虑分批调用和缓存策略，以提升应用的整体性能。例如，可以将频繁请求的结果缓存一段时间，减少重复调用。

结语

通过上述指南，您已经掌握了如何使用通义千问API的基本流程，包括环境配置、API调用、错误处理以及集成应用的方法。随着实践的深入，您可以探索更复杂的场景和使用更多的API特性，以提升应用的功能和用户体验。