用 OpenAI SDK 快速上手 Yeap LLM API

Yeap LLM API 是一个兼容 OpenAI 接口的模型网关。它的设计目标很简单：你不需要学习新的 SDK，也不需要重写代码。保留现有的 OpenAI SDK，把 base_url 换成 https://llm.yeap.cloud/v1，换上 Yeap 的 API 令牌，就可以开始调用。费用按 token 计算，从你的 Yeap 账户余额中扣除，与其他 Yeap 产品共用同一个余额。

可用的接口

所有接口都使用 Authorization: Bearer <令牌> 认证。可用模型和价格会不断更新，最准确的来源永远是 GET /v1/models 或控制台中的模型列表，所以下面的示例都用占位符代替具体的模型名。

第 1 步：创建 API 令牌

登录 console.yeap.cloud，进入 LLM → 令牌，点击创建。创建时可以设置：

• 名称：建议按项目或环境命名，例如 blog-summarizer-prod；
• 配额限制：为这个令牌设置消费上限，或者选择无限配额；
• 模型限制：只允许这个令牌调用指定的模型；
• IP 限制：只接受来自指定 IP 的请求；
• 过期时间：到期后令牌自动失效。

令牌以 sk- 开头，创建后请立即保存。建议每个项目、每个环境使用独立的令牌，并为生产环境之外的令牌设置较低的配额，这样即使令牌泄露，影响也在可控范围内。

把令牌放到环境变量中，不要写进代码仓库：

export YEAP_API_KEY="sk-..."

第 2 步：先用 curl 确认连通

curl https://llm.yeap.cloud/v1/models \
  -H "Authorization: Bearer $YEAP_API_KEY"

返回的 JSON 中，data 数组里每一项的 id 就是可以在请求中使用的模型名。

第 3 步：Python

安装官方 SDK：pip install openai。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YEAP_API_KEY"],
    base_url="https://llm.yeap.cloud/v1",
)

resp = client.chat.completions.create(
    model="your-model-id",  # 从 /v1/models 中选择
    messages=[
        {"role": "system", "content": "你是一个简洁的技术助手。"},
        {"role": "user", "content": "用一句话解释什么是 CDN。"},
    ],
)

print(resp.choices[0].message.content)
print(resp.usage)  # prompt_tokens / completion_tokens / total_tokens

流式输出

对话类应用通常希望逐字显示结果。设置 stream=True，响应会以 Server-Sent Events 的形式陆续到达：

stream = client.chat.completions.create(
    model="your-model-id",
    messages=[{"role": "user", "content": "写一首关于缓存命中的短诗。"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

向量嵌入

emb = client.embeddings.create(
    model="your-embedding-model-id",
    input=["Yeap CDN 支持 HTTP/3", "如何清除缓存"],
)
vectors = [item.embedding for item in emb.data]
print(len(vectors), len(vectors[0]))

图像生成与语音转文字

图像和音频接口同样通过 SDK 的标准方法调用，只是模型名要换成对应类型的模型：

# 图像生成
img = client.images.generate(
    model="your-image-model-id",
    prompt="一张极简风格的服务器机房插画",
    size="1024x1024",
)
print(img.data[0].url or "base64 image returned")

# 语音转文字
with open("meeting.mp3", "rb") as f:
    tr = client.audio.transcriptions.create(
        model="your-transcription-model-id",
        file=f,
    )
print(tr.text)

不同模型返回图像的方式可能不同（URL 或 base64），代码里最好两种都处理。

控制成本的几个习惯

• 设置 max_tokens。输出 token 通常比输入更贵，为每类请求设定合理的输出上限，可以避免模型"说个不停"带来的意外费用。
• 精简上下文。多轮对话时，每一轮都会把历史消息重新发送一遍。对较早的轮次做摘要或截断，输入 token 会少很多。
• 按任务选模型。分类、提取、改写这类简单任务，往往用较小的模型就足够；把大模型留给真正需要推理能力的场景。用 Playground 对比几个模型，再决定默认值。
• 用令牌配额兜底。即使代码里出现循环调用之类的错误，令牌的配额上限也能阻止消费失控。

第 4 步：Node.js

安装：npm install openai。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.YEAP_API_KEY,
  baseURL: "https://llm.yeap.cloud/v1",
});

const stream = await client.chat.completions.create({
  model: "your-model-id",
  messages: [{ role: "user", content: "列出三个降低 API 延迟的方法。" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

不改代码也能切换

官方 OpenAI SDK 会读取环境变量 OPENAI_BASE_URL 和 OPENAI_API_KEY。如果你的工具或脚本已经在使用 OpenAI SDK、又不方便修改代码，可以只改环境变量：

export OPENAI_BASE_URL="https://llm.yeap.cloud/v1"
export OPENAI_API_KEY="$YEAP_API_KEY"

大多数支持"自定义 API 地址"的第三方工具同样适用：把地址填为 https://llm.yeap.cloud/v1，密钥填 Yeap 令牌即可。

错误处理与重试

生产环境中要为失败做好准备：

• 401：令牌无效、已过期，或者请求来自不在 IP 限制名单中的地址。检查令牌设置。
• 额度不足：令牌配额用完或账户余额不足时请求会被拒绝，错误信息中会说明原因。在控制台为令牌调整额度或为账户充值。
• 429 和 5xx：这类错误通常是暂时的，应当带退避重试。OpenAI SDK 内置了重试机制，可以通过 max_retries 调整次数，用 timeout 控制单次请求超时。

client = OpenAI(
    api_key=os.environ["YEAP_API_KEY"],
    base_url="https://llm.yeap.cloud/v1",
    max_retries=3,
    timeout=60.0,
)

观察用量

每个请求都会被记录，包括使用的模型、token 数和费用。在控制台的 LLM 菜单中可以查看调用日志和统计，按令牌区分不同项目的消耗。如果想在写代码之前先比较不同模型的效果，可以使用控制台里的 Playground 直接在浏览器中试验。

小结

接入 Yeap LLM API 只需要三件事：一个令牌、一个 base_url、一个从 /v1/models 里选出的模型名。其余的代码，你已经写好了。