入门概览

如果你是第一次接入 Modelink，可以按这里的步骤完成账号、密钥、接入点、模型和首次验证准备。

前置条件

• 已注册账号并可访问 Modelink 控制台。
• 已按控制台和所在组织要求完成必要认证；未完成认证时，调用频率、可用额度或服务范围可能受限。
• 本地或服务端具备可发起 HTTPS 请求的运行环境。
• 明确要优先体验的方式：API、SDK、第三方客户端、编程工具或业务后端。

最短路径

1. 注册或登录账号，并完成必要认证。
2. 在 Modelink 控制台创建 API Key，并填写用途、环境、业务线或负责人备注。
3. 根据业务区域选择接入点：中国大陆业务可用 https://api.qnaigc.com，海外部署或跨境访问可用 https://api.modelink.ai。
4. 选择模型：简单任务用经济型模型，复杂推理、代码或长上下文任务用高能力模型。
5. 从低风险测试环境开始验证，再进入生产接入。

推荐环境变量

export MODELINK_API_KEY="替换为你的 Modelink API Key"
# 中国大陆 OpenAI 兼容接入点：https://api.qnaigc.com/v1
# 海外 OpenAI 兼容接入点：https://api.modelink.ai/v1
export MODELINK_BASE_URL="https://api.qnaigc.com/v1"
export MODELINK_MODEL="控制台中的模型 ID"

建议将 API Key 放入环境变量、密钥管理服务或 CI/CD Secret，不要写入代码仓库、日志或截图。

SDK 快速验证

如果项目已经使用 OpenAI 兼容 SDK，可以先用最小脚本验证密钥、接入点和模型是否可用：

import OpenAI from "openai";

const model = process.env.MODELINK_MODEL;

if (!model) {
  throw new Error("请先设置 MODELINK_MODEL 环境变量");
}

const client = new OpenAI({
  apiKey: process.env.MODELINK_API_KEY,
  baseURL: process.env.MODELINK_BASE_URL ?? "https://api.qnaigc.com/v1",
});

const response = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "用一句话说明 Modelink 的作用" }],
});

console.log(response.choices[0]?.message?.content);

将上述内容保存为 quickstart.mjs。运行前确认已安装依赖，并且环境变量只在本地 shell、服务端运行环境或 CI/CD Secret 中配置。

npm install openai
node quickstart.mjs

首次验证清单

• 账号是否已完成必要认证，当前环境是否具备调用权限。
• 密钥是否有效，且属于当前环境。
• 接入点是否可访问。
• 目标模型 ID 是否与控制台或模型广场展示一致，并具备所需能力。
• 日志中是否能看到状态码、耗时、请求 ID、模型和 token 用量。
• 是否已设置超时、重试、用量监控和密钥泄露处置方案。

下一步

1. 模型与能力：了解模型能力和选型方式。
2. API 接入点：确认 Base URL、区域和协议兼容策略。
3. 工具、Agent 与客户端接入：在编程工具或业务客户端中配置 Modelink。
4. 故障排查与 FAQ：处理认证、限流、慢请求和质量问题。