用千问 API 完成第一次模型调用：密钥配置与 Python、Node.js、Java 示例

千问模型可以通过 API 调用，接入方式包括 OpenAI 兼容接口和 DashScope SDK 两类。这篇教程要解决的是「第一次把请求发出去」这件事：拿到 API Key、把它安全地放进环境变量、选一门语言写一个最小可运行脚本，并看懂返回结果。适合已经会一点编程、但还没在百炼平台上跑通过一次调用的开发者。如果你只是想和模型对话而不写代码，图形化客户端更省事；需要命令行或脚本里批量调用时，可以配合 千问 这类工具页了解入口，再回到本文按步骤配置。

全文按「账号与密钥 → 环境变量 → 语言示例 → 完整跑通 → 注意事项」的顺序展开。所有示例都只依赖一个环境变量 DASHSCOPE_API_KEY，代码里不出现明文密钥。

准备工作

账号与服务开通

调用千问 API 之前需要完成三件事：

1. 注册账号：没有阿里云账号的先注册。注册过程中如果遇到问题，按注册页面的提示处理。
2. 开通百炼服务：用阿里云主账号进入百炼大模型服务平台，阅读并同意服务协议后会自动开通。如果没有弹出服务协议，说明该账号已经开通过了。
3. 完成实名认证：开通时若提示「您尚未进行实名认证」，需要先完成实名认证，再回来开通。

创建 API Key

进入 API Key 管理页面，点击创建 API Key 即可。创建时不需要选择模型——具体调用哪个模型由请求体里的 model 参数决定，例如 model="qwen-plus"。可用模型清单以平台当前的模型列表为准。

如果希望限制这把 Key 的使用范围，创建时选择「自定义」权限，并打开「访问模型范围」开关，之后这把 Key 只能调用被勾选的模型。这个设置适合把 Key 分发给不同项目或不同同事时做隔离。

确认业务空间 ID 与地域

使用华北 2（北京）、新加坡、日本（东京）、德国（法兰克福）或中国香港地域的模型时，Base URL 中需要填入业务空间 ID（WorkspaceId）。业务空间 ID 可以在业务空间管理页面查看。不同地域的 URL 和 region 取值不同，示例代码里给的是华北 2（北京）的写法，换成其他地域时要同步修改。

把 API Key 写入环境变量

不建议把 Key 直接写进代码。推荐的做法是配置到环境变量 DASHSCOPE_API_KEY，代码通过读取环境变量获取。下面按操作系统分别说明。

Linux（永久生效）：把导出语句追加到 ~/.bashrc，然后重新加载。

echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
source ~/.bashrc
echo $DASHSCOPE_API_KEY

也可以手动编辑：执行 nano ~/.bashrc，在文件里加入 export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"，按 Ctrl + X、再按 Y、再按 Enter 保存退出，然后 source ~/.bashrc。最后重新打开一个终端窗口，用 echo $DASHSCOPE_API_KEY 验证。

Linux（仅当前会话）：直接在当前终端执行导出命令，关闭窗口即失效。

export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
echo $DASHSCOPE_API_KEY

macOS：先执行 echo $SHELL 确认默认 Shell。Zsh 用户把导出语句追加到 ~/.zshrc；Bash 用户追加到 ~/.bash_profile。两者都是改完后 source 对应文件，再新开终端验证。

# Zsh
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
source ~/.zshrc

# Bash
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile
source ~/.bash_profile

macOS 上的临时变量对 Zsh 和 Bash 都适用：

export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
echo $DASHSCOPE_API_KEY

Windows（图形界面，永久生效）：按 Win + Q 搜索「编辑系统环境变量」，打开系统属性窗口，点击「环境变量」，在「系统变量」区域点击「新建」，变量名填 DASHSCOPE_API_KEY，变量值填你的 Key，然后依次点三个窗口的「确定」。注意两点：修改系统环境变量需要管理员权限；已经打开的命令窗口、IDE 或其他程序不会立即读到新值，需要重启程序或新开一个命令行窗口。

验证时，CMD 用 echo %DASHSCOPE_API_KEY%，PowerShell 用 echo $env:DASHSCOPE_API_KEY。

Windows（CMD）：永久写入用 setx，之后必须新开窗口才生效；临时变量用 set，只在当前会话有效。

REM 永久
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"

REM 临时
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
echo %DASHSCOPE_API_KEY%

Windows（PowerShell）：永久写入用 [Environment]::SetEnvironmentVariable 并指定 User 作用域，同样需要新开窗口；临时变量直接赋值给 $env:。

# 永久
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

# 临时
$env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"
echo $env:DASHSCOPE_API_KEY

操作步骤

第一步：准备 Python 环境

Python 需要 3.9 或以上版本。先确认版本和 pip 是否可用：

python -V
pip --version

如果报「'python' 不是内部或外部命令」或 -bash: python: command not found，分两种情况处理。Windows 上确认安装 Python 时勾选了「Add python.exe to PATH」，装好后关闭当前终端重新打开；Linux 和 macOS 上先用 which python pip 查一下，如果返回的是 /usr/bin/python3 和 /usr/bin/pip3，说明系统里命令名带 3，后续命令把 python 换成 python3、pip 换成 pip3 即可。

可选地创建虚拟环境，避免和其他项目的依赖冲突：

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

然后安装 SDK。两种 SDK 任选其一：

pip install -U openai
# 或
pip install -U dashscope

终端出现 Successfully installed ... openai-x.x.x 或 ... dashscope-x.x.x 即安装成功。

第二步：用 OpenAI Python SDK 调用

新建 hello_qwen.py，写入下面的代码。注意 import os 不能省，它负责读取环境变量；如果改用 .env 文件管理密钥，需要同时导入 os 和 dotenv 并调用 load_dotenv()。缺少 import os 会抛 NameError，不要误判成 .env 加载失败。

import os
from openai import OpenAI

try:
    client = OpenAI(
        # 若没有配置环境变量，请用 API Key 替换下行：api_key="sk-xxx",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # 华北2（北京）地域的 URL，其他地域不同；{WorkspaceId} 替换为真实业务空间 ID
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    )
    completion = client.chat.completions.create(
        model="qwen-plus",
        messages=[
            {'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': '你是谁？'}
        ]
    )
    print(completion.choices[0].message.content)
except Exception as e:
    print(f"错误信息：{e}")

运行：

python hello_qwen.py
# 或
python3 hello_qwen.py

如果提示 No such file or directory，说明当前目录下没有这个文件，在文件名前补上完整路径。运行成功会打印模型对「你是谁？」的回答。

第三步：用 DashScope Python SDK 调用

DashScope SDK 的写法与 OpenAI SDK 不同：它用 Client 对象承载密钥、业务空间和地域，消息内容用 text 字段包装，返回结果从 output_text 取。

import os
import dashscope
from dashscope.v2 import DashScopeError

client = dashscope.Client(
    # 若没有配置环境变量，请用 API Key 替换下行：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

messages = [
    {'role': 'system', 'content': [{'text': 'You are a helpful assistant.'}]},
    {'role': 'user', 'content': [{'text': '你是谁？'}]}
]

try:
    response = client.multimodal.chat.create(
        model="qwen-plus",
        messages=messages,
    )
    print(response.output_text)
except DashScopeError as e:
    print(f"HTTP返回码：{e.status_code}")
    print(f"错误码：{e.code}")
    print(f"错误信息：{e.message}")

运行方式与上一步相同。这段代码把 workspace 和 region 显式写在客户端初始化里，换地域时改这两个值，不要只改 URL。

第四步：用 Node.js 调用

先确认 Node.js 和 npm 可用：

node -v
npm -v

没有 Node.js 的话去官网下载安装。然后在项目目录安装 OpenAI SDK：

npm install --save openai
# 或
yarn add openai

安装失败时可以配置镜像源后重试。终端出现 added xx package in xxs 表示成功，用 npm list openai 可以查具体版本。

新建 hello_qwen.mjs：

import OpenAI from "openai";

try {
  const openai = new OpenAI({
    // 若没有配置环境变量，请用 API Key 替换下行：apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  });

  const completion = await openai.chat.completions.create({
    model: "qwen-plus",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "你是谁？" }
    ],
  });

  console.log(completion.choices[0].message.content);
} catch (error) {
  console.log(`错误信息：${error}`);
}

运行：

node hello_qwen.mjs

两个常见问题：一是运行命令要在文件所在目录执行，否则在文件名前写完整路径；二是 SDK 必须和脚本装在同一目录，否则会报 Cannot find package 'openai' imported from xxx。运行时如果出现 punycode 模块的 DeprecationWarning，属于 Node.js 自身的弃用提示，不影响调用结果。

第五步：用 Java 调用

DashScope Java SDK 要求 Java 8 或以上。检查版本：

java -version
# 可选，使用 Maven 构建时
mvn --version

在 Maven 项目的 pom.xml 的 <dependencies> 里加入依赖，把 the-latest-version 换成当前最新版本号：

<dependency>
  <groupId>com.alibaba</groupId>
  <artifactId>dashscope-sdk-java</artifactId>
  <version>the-latest-version</version>
</dependency>

保存后执行 mvn compile 或 mvn clean install，Maven 会自动下载依赖。Java 侧的调用代码同样从环境变量读取 DASHSCOPE_API_KEY，模型名通过请求参数传入，与 Python、Node.js 示例保持一致。

一个完整示例

下面把前面的步骤串成一条从零到出结果的最短路径，以 Python + OpenAI SDK 为例。

1. 确认前置条件：账号已注册、百炼已开通、实名认证已完成、API Key 已创建。

2. 写入环境变量并验证：

export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
echo $DASHSCOPE_API_KEY

输出应当是你的 Key 本身。如果输出为空，说明变量没写进去，先解决这一步再往下走。

3. 准备环境：

python -V
pip install -U openai

4. 写入脚本 hello_qwen.py：

import os
from openai import OpenAI

try:
    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': 'You are a helpful assistant.'},
            {'role': 'user', 'content': '你是谁？'}
        ]
    )
    print(completion.choices[0].message.content)
except Exception as e:
    print(f"错误信息：{e}")

5. 运行并读取结果：

python hello_qwen.py

正常输出是一段自我介绍式的回答。到这里，一次完整的「取密钥 → 配环境 → 发请求 → 取文本」链路就跑通了。之后要换模型，只改 model 参数；要换地域，改 base_url 并补上业务空间 ID；要换语言，参考前面 Node.js 或 Java 的写法，逻辑完全一致。

注意事项

• API 调用与操作系统版本无关，只要网络能连通就能用。环境变量配置失败通常不是系统兼容问题，而是变量没生效或终端没重开。
• 环境变量改动不会影响已打开的程序。Windows 上尤其明显：改完系统变量后，已经开着的 CMD、PowerShell、IDE 都读不到新值，必须新开窗口或重启程序。
• 创建 API Key 时不选模型。模型由请求体的 model 字段决定，写错模型名会在调用时报错，而不是在创建 Key 时报错。
• 业务空间 ID 不能漏。使用华北 2（北京）、新加坡、日本（东京）、德国（法兰克福）、中国香港地域时，Base URL 里要填 WorkspaceId；DashScope SDK 则通过 workspace 和 region 两个参数指定。
• 不要省略 import os。用 .env 管理密钥时，缺少它会抛 NameError，容易被误认为文件加载失败。
• SDK 与脚本要在同一目录。Node.js 下跨目录运行会报 Cannot find package 'openai'。
• 命令名带不带 3 取决于系统。Linux、macOS 上如果 which python pip 找不到，改用 python3、pip3。
• 模型清单、可用地域、配额与计费方式会调整，本文示例中的模型名仅作演示，实际使用前请以官网当前信息为准。