AI SDK 简介与环境搭建

使用 AIHubMix API Key 和 OpenAI 官方 JavaScript SDK,在 Node.js 中完成第一次模型调用。

🎯 引言

开发 AI 应用时,我们需要把用户的问题发送给大语言模型,再接收模型生成的回答。本篇会使用 OpenAI 官方 JavaScript SDK 发起请求,使用 AIHubMix 提供模型 API 服务,在 Node.js 中完成第一次模型调用。

你将学会区分 SDK、聚合平台和模型,了解如何获取 API Key、配置调用地址、运行代码,以及遇到连接失败时怎样排查。本篇只讲第一次请求,多轮对话和流式输出留给后面的文章。


🧱 认识 SDK、AIHubMix 和模型

先把三个角色区分清楚:

名称负责什么本篇使用
OpenAI SDK在 JavaScript 中构造请求、发送请求并读取响应openai npm 包
AIHubMix接收请求并将其转发给可用的模型服务https://aihubmix.com/v1
大语言模型根据输入内容生成回答gpt-4o-mini

模型 API 是平台提供的调用接口,可以直接发送 HTTP 请求访问,也可以通过 SDK 调用。 SDK 封装了请求发送、API Key 传递和响应处理等操作 ,让我们可以直接使用 JavaScript 方法。API Key 是否有效,由接收请求的 AIHubMix 验证。

简单来说: Node.js 程序使用 OpenAI SDK,把请求发给 AIHubMix,再由平台调用指定模型,最后把结果返回程序。

AIHubMix 是聚合 API 平台,不是模型本身。它提供与 OpenAI 兼容的接口,因此我们可以继续使用熟悉的 openai 包,不需要安装 AIHubMix 专属 SDK。这里的「兼容」主要指约定好的请求格式,不能认为所有模型、参数与高级能力完全相同。

本课程统一使用 OpenAI SDK 的 Chat Completions API 调用模型。它通过消息列表向模型提供输入,并返回模型生成的回答。后续文章将继续使用这种方式学习多轮对话、流式输出等功能。


🔑 注册 AIHubMix 并准备 API Key

打开 AIHubMix 官网 注册或登录账户,在控制台中找到 API Key 的创建入口,生成自己的密钥。

第三方平台的页面可能更新,入口名称和位置以实际界面为准。API Key 只保留在本机或服务端,不要写进前端代码、提交到 Git 仓库或发送给其他人。

支付宝充值与费用说明

AIHubMix 支持 支付宝充值 。根据平台的 支付宝充值说明,可以在账户额度页面选择支付宝充值入口,按提示进行小额充值。

需要注意, 充值 1 美元额度,不代表支付宝只会扣除按实时汇率换算的人民币金额 。例如,一次充值 1 美元额度,支付宝实际支付了 9 元人民币,按当时的市场参考汇率计算, 溢价约 34.9% 。这只是该笔充值的溢价,不代表平台固定收取 34.9% 的手续费;实际付款金额以支付页面为准。

充值后获得的是账户额度,调用付费模型时会按平台的模型定价扣费。AIHubMix 还提供部分有额度限制的免费模型,是否能够使用以及有哪些限制,以平台当前说明为准。


🛠 创建项目并发送第一次请求

先确认当前使用的 Node.js 版本:

node -v

本课程示例使用 Node.js 24.x。如果版本不符合要求,请先切换到对应版本,再继续创建项目。

创建目录、初始化项目,然后安装指定版本的 OpenAI SDK:

mkdir ai-sdk-course
cd ai-sdk-course
npm init -y
npm install --save-exact openai@7.62.0

保存模型配置

在项目根目录创建 .env 文件,将 AIHubMix 的 API Key、接口地址和模型名称保存在这里:

AI_API_KEY=替换成你的 AIHubMix API Key
AI_BASE_URL=https://aihubmix.com/v1
AI_MODEL=gpt-4o-mini

这里的三个配置分别表示:

  • AI_API_KEY:AIHubMix 生成的密钥,不是 ChatGPT 的登录凭证,也不是 OpenAI 官方平台的密钥。
  • AI_BASE_URL:API 请求的目标地址,指向 AIHubMix 的 OpenAI 兼容接口。
  • AI_MODEL:使用的模型 ID。这里的 gpt-4o-mini 是付费模型,调用时会消耗账户额度;平台提供的免费调用额度只适用于指定模型。

.env 文件中的配置会保存在本地。运行程序时,通过 --env-file=.env 加载配置,不需要每次重新设置环境变量。

.env 包含真实 API Key,不要提交到 Git 仓库,也不要发给他人。在项目根目录创建 .gitignore 文件,加入以下内容:
.env
node_modules/

新建 index.mjs:

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.AI_API_KEY,
    baseURL: process.env.AI_BASE_URL
});

const response = await client.chat.completions.create({
    model: process.env.AI_MODEL,
    messages: [
        {
            role: "user",
            content: "请给一个待办事项应用写一句简短的产品介绍。"
        }
    ]
});

console.log("模型名称:", response.model);
console.log("模型回复:", response.choices[0].message.content);
console.log("Token 消耗:", response.usage);

先理解代码中的几个关键位置:

  1. new OpenAI() 创建调用客户端。我们显式传入 apiKey 与 baseURL,所以请求会发给 AIHubMix ,而不是 OpenAI 官方接口。
  2. chat.completions.create() 向模型发送一次消息。messages 中的 role: "user" 表示用户提出的问题。
  3. response.choices[0].message.content 读取模型返回的正文。
  4. response.usage 查看这次请求使用的输入和输出 Token 数量,后续会结合模型定价介绍如何计算费用。如果平台没有返回某些字段,以实际响应为准。

运行程序

如果当前网络环境能够直连 AIHubMix,可以运行:

node --env-file=.env index.mjs

--env-file=.env 会在程序启动前读取项目根目录的配置文件,将变量提供给 process.env。

如果直连超时,且已启用本地 HTTP 代理,可以在支持环境代理的 Node.js 24.x 中这样运行:

HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env index.mjs

NODE_USE_ENV_PROXY=1 让 Node.js 读取代理环境变量;7890 是本地 HTTP 代理端口,实际使用时应以代理软件的配置为准。

终端可能输出:

模型名称: gpt-4o-mini-2024-07-18
模型回复: 轻松记录日常待办,让任务安排一目了然。
Token 消耗: { prompt_tokens: 25, completion_tokens: 19, total_tokens: 44 }

模型回复与 Token 数量不是固定的。 只要返回了与问题相关的文字,就说明第一次调用已经成功。


🪤 常见错误与排查

现象优先检查
401API Key 是否填写正确,是否误用了其他平台的 Key
403账号权限、额度状态以及具体平台错误说明
404 或模型不存在AI_MODEL 是否是平台当前支持的准确模型 ID
429模型调用额度或频率限制,避免不停重试
连接超时网络连接、代理端口及 Node.js 是否正确读取代理配置

如果怀疑 .env 未加载,可以检查程序是否读到了 API Key,而不打印密钥内容:

node --env-file=.env -e 'console.log(process.env.AI_API_KEY ? "API Key 已加载" : "API Key 未加载")'

如果看到“API Key 未加载”,请检查 .env 的文件名、位置和配置项。

如果仍然超时,可以先确认代理软件确实运行,并核对 127.0.0.1:7890 是否是其 HTTP 代理地址;如果不使用代理,也可以去掉代理前缀重新尝试。


❓ 知识问答

Q1:使用 OpenAI SDK,为什么不需要 OpenAI 官方的 API Key?

因为我们已经把 baseURL 设置为 AIHubMix,SDK 发送的请求由 AIHubMix 接收和鉴权,所以需要使用 AIHubMix 签发的 Key 。

Q2:充值了 1 美元,是否代表只能调用 OpenAI 模型?

不是。AIHubMix 支持不同模型供应商,但每种模型的可用性、接口兼容性和价格可能不同。充值是平台额度,具体模型是否支持还要查看平台的模型列表。


🧪 小练习

把 index.mjs 中的问题替换为“请为一个天气查询应用写一句简短的产品介绍”,重新运行,观察回复是否变化。

接着,临时把 AI_MODEL 改成一个不存在的模型 ID,再次运行。记下收到的错误类型,并将模型 ID 恢复为正确值。最后解释:为什么这次请求的密钥来自 AIHubMix,但代码仍然使用 OpenAI SDK?


🎉 你已经完成 AIHubMix 配置、OpenAI SDK 安装和第一次模型调用。下一篇继续学习文本生成的请求参数与响应数据。