Yuan · 开发文档

1. 文档怎么用

如果你只是要把业务接到 Yuan，按顺序看“快速开始”、“CLI 工具配置”、“请求格式”三段即可。管理员或运维排障时，再看模型扣费、流式错误和发布检查。

第一步

拿到用户 API Key

在控制台创建用户 Key。完整 Key 只展示一次，列表页只应显示掩码。

第二步

确认模型 ID

请求里的 model 必须和后台可见模型完全一致。大小写和后缀都要一致。

第三步

检查日志和余额

一次成功请求应该能在日志里看到模型、Token、费用和状态。

基础地址固定使用 https://yuann.ai/v1。 不要把后台管理员密码、上游渠道 Key 或支付密钥填进客户端配置。外部程序只使用用户 API Key。

你要做什么	优先看	判断标准
SDK 接入	快速开始、请求格式	接口返回正常，日志里有记录。
配置 Claude Code / Codex / Gemini CLI	CLI 工具配置	工具配置里只出现 Base URL、用户 Key、模型名。
排查 401 / 403	密钥和认证	确认没有把登录密码当成 API Key。
排查 429 / 503	流式与错误、发布排障	先看用户组、渠道健康、上游错误和重试策略。

2. 快速开始

只做三件事：拿 Key，选模型，发请求。跑通后再接入生产参数、流式输出和重试逻辑。

Step 1: Get API Key

登录控制台，进入 API 密钥页面，创建一把当前项目专用 Key。

Step 2: Choose Model

从模型列表或管理员配置中复制模型 ID，例如 gpt-4o-mini。

Step 3: Make Request

把 Base URL 设置为 https://yuann.ai/v1，发送下面任意一种示例。

只复制示例里的占位符。 YOUR_API_KEY 必须换成你自己的用户 Key。不要在截图、工单、聊天记录或公开仓库里粘贴真实 Key。

                  
chat-completions

curl -sS https://yuann.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "用一句话确认接入成功。"}
    ],
    "temperature": 0.2
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://yuann.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句话确认接入成功。"}],
    temperature=0.2,
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://yuann.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "用一句话确认接入成功。" }],
  temperature: 0.2,
});

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

成功后应该看到两处变化。 客户端拿到模型回复；控制台日志能看到请求时间、模型、Token、费用和状态。如果只有客户端成功但日志缺失，优先检查请求是否真的经过 Yuan 网关。

3. CLI 工具配置

下面只展示接入 Yuan 所需字段。不同工具的字段名可能不同，但核心始终是 Base URL、API Key 和模型 ID。

Claude Code

使用兼容端点时，配置基础地址和用户 Key。按你的系统选择命令。

setx ANTHROPIC_BASE_URL "https://yuann.ai/v1" setx ANTHROPIC_API_KEY "YOUR_API_KEY"

Codex

在配置文件里使用 Yuan 兼容地址，模型名填写平台可见模型。

# %USERPROFILE%\.codex\config.toml model = "gpt-4o-mini" base_url = "https://yuann.ai/v1" api_key = "YOUR_API_KEY"

Gemini CLI

如果工具支持 OpenAI 兼容模式，优先使用 OpenAI 风格环境变量。

setx OPENAI_BASE_URL "https://yuann.ai/v1" setx OPENAI_API_KEY "YOUR_API_KEY"

配置后重新打开终端。 Windows 的 setx 会写入后续新终端；当前已打开的窗口通常不会立即继承新值。macOS / Linux 若写入 shell 配置文件，也需要重新加载。

4. 密钥和认证

平台里有三类身份，不能混用：控制台登录账号、用户 API Key、管理员后台配置权限。

控制台账号

用于登录页面和查看账单、日志、密钥。它不是模型调用凭证。

用户 API Key

用于外部程序调用 /v1 模型接口。建议按项目、环境、租户拆分。

管理员权限

用于配置渠道、分组、倍率、支付和系统参数。不要暴露给普通用户。

场景	正确做法	常见错误
服务端调用模型	`Authorization: Bearer YOUR_API_KEY`	把控制台登录密码放进 Authorization。
浏览器前端	只调用自己的业务后端，由后端保管 Key。	把真实 Key 写进网页源码或 localStorage。
排查问题	记录变量名、长度、创建时间、权限范围。	在日志、截图或 AI 记忆里粘贴完整 Key。

怀疑泄漏时直接换 Key。 禁用旧 Key，创建新 Key，更新服务端环境变量，然后确认旧 Key 不再出现在近期请求日志里。

5. 请求格式

外部模型调用走 /v1 兼容层；控制台页面走 /api。排查时先看路径，就能判断问题在模型调用链还是控制台链路。

POST

/v1/chat/completions

聊天补全接口。常用字段是 model、messages、temperature、max_tokens、stream。

POST

/v1/responses

Responses 兼容接口。适合使用统一 input/output 结构的客户端。

GET

/v1/models

列出当前 Key 可见模型。模型缺失时检查用户分组、渠道映射和启用状态。

GET

/api/log/self/

控制台查看当前用户调用日志。外部 SDK 不应依赖该接口。

{ "model": "gpt-4o-mini", "messages": [ {"role": "system", "content": "You are concise."}, {"role": "user", "content": "Say hello in Chinese."} ], "stream": false, "temperature": 0.2 }

路径：不要重复写 /v1/v1，也不要少写 /v1。
模型：必须使用后台实际启用的模型 ID。
超时：业务服务端设置请求超时和重试上限。
日志：保存 request id、模型、状态码和错误摘要，不保存完整密钥。

6. 模型与扣费

模型名是用户请求入口，渠道是后台实际转发资源。扣费时要同时看模型价格、分组倍率、Token 统计和请求是否成功结算。

模型选择

简单分类、格式化、短回复使用低成本模型。
复杂推理、长上下文、工具调用使用更强模型，并设置预算。
生产业务不要硬编码实验模型名，至少准备一个备用模型。

扣费检查

先确认充值金额和余额入账是否正确。
再核对模型价格、用户分组倍率和 token 数。
最后检查失败请求是否退还或未扣费。

配置项	含义	排查重点
模型价格	模型基础消耗单价。	确认模型 ID 是否命中正确价格。
分组倍率	用户所属分组的倍率。	确认用户实际分组，而不是只看前端展示。
渠道倍率	上游渠道成本或路由权重相关配置。	确认是否影响最终结算或仅影响渠道选择。
Token 统计	输入、输出、缓存、补图等计量。	流式和非流式应得到一致的最终结算记录。

前端显示只能作为入口。 真正结算以后台日志和数据库记录为准。页面显示异常时，先核对接口返回，再判断是不是缓存或静态文案问题。

7. 流式与错误

流式响应适合聊天界面和长文本生成。客户端要按 SSE 或兼容格式逐行读取，不要把流式响应当成普通 JSON 一次性解析。

curl -N https://yuann.ai/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "stream": true, "messages": [{"role": "user", "content": "写一个三行摘要。"}] }'

状态码	常见含义	处理方式
401	Key 缺失、错误或已禁用。	检查 Authorization、Key 状态和是否误用登录密码。
403	分组、模型或权限不允许。	检查用户分组、模型可见性和后台策略。
429	限流、余额不足或上游频率限制。	降低并发，检查余额、组限额和上游配额。
503	可用渠道不足或上游不可用。	检查渠道健康、模型路由、上游状态和重试窗口。

重试要有上限。 建议只对 408、429、500、502、503、504 做指数退避重试，并保留最大次数。401 和 403 通常不是重试能解决的问题。

8. 发布排障

文档页属于 cldapi 静态主题。修改 HTML、CSS 或 JS 后，容器部署需要重建后端镜像，确保 Go 嵌入的静态资源已经更新。

发布前检查

docs.html 和 pages/docs.html 内容一致。
docs-i18n.js 英文内容和中文结构一致。
代码块复制按钮、语言 tabs、目录高亮可用。
页面不包含真实 API Key、token、password 或完整 Authorization。

上线后验证

curl -I https://yuann.ai/docs.html curl -I https://yuann.ai/pages/docs.html curl -I https://yuann.ai/css/docs.css?v=20260520-docs-v3 curl -I https://yuann.ai/js/docs-i18n.js?v=20260521-flow

现象	优先检查	判断
点击文档还是旧页面	HTML 里的版本号、浏览器缓存、CDN 缓存。	确认 JS 请求命中了 `20260521-flow`。
英文切换后按钮失效	DOM 替换后是否重新初始化 tabs 和复制按钮。	点击语言切换后仍能复制当前代码块。
页面 200 但样式丢失	CSS 路径、Content-Type、反向代理 rewrite。	`docs.css` 返回 text/css。
接口 503	渠道健康、模型路由、上游状态、用户分组。	不要只看上游根路径 200，要看真实模型调用。