阿里云百炼平台 API 接入教程（附 Node.js + TypeScript 实战）

阿里云百炼平台 API 接入教程（附 Node.js + TypeScript 实战）

• 为什么选阿里云百炼？
• 第一步：注册阿里云百炼账号
• • 注册并进入控制台
  • [获取 API Key](#获取 API Key)
  • 额度查询
• [第二步：项目初始化 - 创建 Node.js + TypeScript 环境](#第二步：项目初始化 - 创建 Node.js + TypeScript 环境)
• • [创建 .env 文件 - 存放 API Key](#创建 .env 文件 - 存放 API Key)
  • [创建 .gitignore - 防止 API Key 误上传](#创建 .gitignore - 防止 API Key 误上传)
• [基础对话实战：纯 API 单轮调用](#基础对话实战：纯 API 单轮调用)
• • 配置环境变量
  • 编写代码
• 大模型核心参数详解
• [踩坑总结：国内 API 调用的常见问题](#踩坑总结：国内 API 调用的常见问题)
• • 跨域问题
  • [`InvalidApiKey` 或 `401` 鉴权错误](#InvalidApiKey 或 401 鉴权错误)
  • [`model not found`](#model not found)
  • 请求频率限制
  • 响应内容为空
• 结语

本篇将讲解阿里云百炼平台的 API 接入方法，以及如何配置开发环境。

为什么选阿里云百炼？

国内目前大模型平台众多，本文以阿里云百炼为例进行讲解。。以下是针对前端场景的选型对比：

平台	核心模型	前端适配性优势
阿里云百炼	通义千问 (Qwen)	OpenAI SDK 完全兼容，代码迁移成本极低；官方维护 Node.js SDK，生态齐全；新用户有免费额度。
火山引擎方舟	豆包 (Doubao)	同样兼容 OpenAI 协议，在生成创意文案（如营销标题）时表现力强。
DeepSeek	DeepSeek-V3	价格便宜，但免费额度已停止赠送，适合预算有限的个人开发者。

第一步：注册阿里云百炼账号

与 DeepSeek API 一样，我们在使用阿里云百炼时，也需要先拿到那把"钥匙"------API Key。

注册并进入控制台

打开阿里云百炼平台，点击右上角"登录"（可以直接使用支付宝、淘宝等账号登录）。

获取 API Key

登录完成后，点击"立即体验Qwen3.6"按钮，即可进入阿里云百炼平台控制台。在控制台左侧菜单找到 API Key。

• 点击 创建 API Key。
• 归属空间：建议选"默认业务空间"，这里的 Key 可以调用大多数标准模型。
• 复制 Key ：创建后点击图标复制（格式是一串字母数字组合）。请妥善保存，不要上传到 GitHub！
  

注：阿里云百炼的 API Key 创建成功后，可随时复制，不用担心忘记保存！

额度查询

在 API KEY 创建完成后，大多数人比较关心的就是额度问题了：

• 点击 模型
• 在左侧导航栏中选择 模型用量 ，就可以看到自己的额度了
  

第二步：项目初始化 - 创建 Node.js + TypeScript 环境

如果你还没有项目，初始化一个：

mkdir bailian-demo
cd bailian-demo
npm init -y

# 安装核心依赖
npm install openai dotenv
npm install -D typescript tsx @types/node

# 初始化 TS 配置
npx tsc --init

创建 .env 文件 - 存放 API Key

在项目根目录创建 .env 文件：

BAILIAN_API_KEY=你的API Key
BAILIAN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

注意 ：compatible-mode 是阿里云百炼的 OpenAI 兼容模式入口，用这个地址代码写法就和调用 OpenAI 完全一样。

创建 .gitignore - 防止 API Key 误上传

.env
node_modules

对于需要上传 GIT 的同学来说，还是得先建 .gitignore 再写代码，以免 API Key 泄漏。

基础对话实战：纯 API 单轮调用

现在我们开始写代码。阿里云百炼完美兼容 OpenAI 的 SDK 语法，这使得我们的接入异常简单。

配置环境变量

在项目根目录创建 .env 文件存放密钥：

BAILIAN_API_KEY=你的API Key
BAILIAN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

注意 ：compatible-mode 是阿里云百炼的 OpenAI 兼容模式入口，用这个地址代码写法就和调用 OpenAI 完全一样。

编写代码

创建 src/index.ts，手写第一段 AI 代码：

import OpenAI from 'openai';
import dotenv from 'dotenv';

dotenv.config();

// 1. 初始化客户端（兼容 OpenAI 写法）
const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: process.env.DASHSCOPE_API_URL,
});

// 2. 核心对话函数：纯 API 单轮调用
async function singleTurnChat() {
  try {
    console.log("🤖 大模型思考中...\n");

    const response = await client.chat.completions.create({
      model: 'qwen-turbo', // 推荐 qwen-turbo（最快最便宜），也可用 qwen-plus（更聪明）
      messages: [
        {
          role: 'system',
          content: '你是一个资深的前端技术专家，擅长用简洁幽默的语言解释复杂概念。'
        },
        {
          role: 'user',
          content: '请解释一下什么是"虚拟DOM"？用一句话总结。'
        }
      ],
      temperature: 0.7,   // 控制随机性
      top_p: 0.9,        // 核采样
    });

    const aiMessage = response.choices[0]?.message?.content;
    console.log('✅ 大模型回复：', aiMessage);
    console.log('\n📊 Token 消耗：', response.usage);
    
  } catch (error: any) {
    console.error('❌ 请求失败：', error.message);
  }
}

singleTurnChat();

在终端执行 node index.ts，如果一切顺利，你就能看到 AI 给出的回答了:

🤖 大模型思考中...

✅ 大模型回复： 虚拟DOM就是网页的"幕后替身"，它是一个轻量的JavaScript对象，用来高效地描述真实DOM的状态，避免频繁操作真实DOM带来的性能问题。

📊 Token 消耗： {
  completion_tokens: 35,
  prompt_tokens: 47,
  prompt_tokens_details: { cached_tokens: 0 },
  total_tokens: 82
}

大模型核心参数详解

在代码中，我们调整了 temperature 和 top_p，这两个参数对结果影响巨大。

参数	取值范围	前端业务场景说明
Temperature	0 ~ 2.0	"严谨度"开关 。越低输出越确定。 • 0.1：适合代码生成 、JSON 提取 ，要求格式绝对精准。 • 1.2：适合AI 文案 、客服话术，需要多样性。
Top_p	0 ~ 1.0	"词汇池"筛选 。核采样参数。 • 0.1：模型只在概率最高的几个词里选，回答很死板 。 • 0.9：候选词变多，回答更生动。
Max Tokens	动态	约束输出长度 。限制的是输出长度，不是输入。可以防止 AI "话痨"。
Messages	数组	上下文窗口。将历史对话放在这里，模型就能记住之前说了什么，实现多轮对话。

前端调优经验：

• 做 代码注释生成 或 日志分析 时，Temperature 调到 0.2 以下，不然模型容易"幻觉"编造代码。
• 做 智能客服 或 情感分析 时，Temperature 调到 0.8 左右，回复会更有人情味。

踩坑总结：国内 API 调用的常见问题

在实际调试过程中，我们可能会遇到一些报错，下面是我整理好的避坑指南：

跨域问题

• 现象 ：直接在浏览器控制台用 fetch 请求阿里云接口
• 发生原因 ：百炼的大模型 API 通常不支持浏览器直接调用（没有配置 CORS 头）
• 解决方法 ：后端代理。实战练习中务必使用 Node.js 环境，或者用 Next.js 的 API Routes 做中转

InvalidApiKey 或 401 鉴权错误

• 现象：401 Unauthorized
• 发生原因：API Key 写错了，或者 Base URL 不对
• 解决方法 ：检查 .env 中的 Key 是否正确复制；确认 Base URL 是 https://dashscope.aliyuncs.com/compatible-mode/v1

model not found

• 现象：400 错误，找不到模型
• 发生原因 ：模型名称写错了，比如 qwen-turbo 写成了 qwenturbo
• 解决方法 ：严格对照官方文档的 Model ID ，新手无脑先试 qwen-turbo

请求频率限制

• 现象：429 Too Many Requests
• 解决方法 ：Coding Plan 并发有限，不要用 Promise.all 同时发 100 个请求。添加重试机制或引入 p-limit 库控制并发

响应内容为空

• 现象 ：response.choices[0]?.message?.content 是 undefined
• 发生原因：可能触发了内容安全过滤
• 解决方法：检查 prompt 是否包含敏感词，或者尝试换一个更温和的问题

结语

通过这篇教程，我们不仅拿到了 API Key，还运行了第一段 TS 代码，理解了 temperature 参数的含义。

对于文章中错误的地方或有任何疑问，欢迎在评论区留言讨论！