AB
AiBoss
チュートリアル

胜算云

チュートリアル

用胜算云统一 API 调用多个大模型:密钥配置与流式调用实战

胜算云提供一个 OpenAI 兼容的统一端点,用同一个 Base URL 和 API Key 就能切换不同厂商的模型。本文从创建密钥讲起,给出 Python、Node.js、curl 三种流式调用写法,并说明参数含义、常见报错排查与密钥管理要点。

胜算云提供的是一个 OpenAI 兼容的统一调用入口:所有模型共用同一个 Base URL 和同一个 API Key,切换模型时只改请求里的 model 字段即可。平台会根据请求内容自动路由到它认为合适的模型,目的是降低调用成本、提升响应质量。这篇教程面向已经拿到密钥、准备把胜算云接进自己脚本或服务的开发者,重点讲清楚三件事:密钥怎么建、请求怎么发、流式响应怎么正确读出来。如果你更习惯用现成的客户端工具而不是自己写代码,可以先通过 胜算云 了解它的整体能力,再回到本文看接口层面的细节。

准备工作

账号与密钥

调用之前需要先在胜算云控制台注册并登录账号,然后在「API 密钥」模块里创建并复制自己的专属密钥。整个流程只有三步:

  1. 访问胜算云控制台,注册并登录账号。
  2. 进入「控制台」页面。
  3. 在「API 密钥」模块创建密钥,复制生成的字符串。

创建密钥时需要注意当前账户的 RPM(每分钟请求数)与 TPM(每分钟 token 数)限制。这两个值决定了你的并发能力上限,如果对额度有疑问,应当联系客服确认,而不是靠试错去猜。密钥等同于账号凭证,不要写进前端代码、不要提交到公开仓库,也不要贴进聊天窗口。

两个固定值

接入时只需要记住两个常量,所有兼容接口都复用它们:

项目值
Base URLhttps://router.shengsuanyun.com/api/v1
认证方式Authorization: Bearer YOUR_API_KEY

注意 Base URL 末尾带 /api/v1,这是 OpenAI SDK 期望的形式——SDK 会自己在后面拼接 /chat/completions 等路径。如果你用 curl 直接发请求,则要写完整的 https://router.shengsuanyun.com/api/v1/chat/completions。这是新手最容易踩的坑之一:把 Base URL 直接当请求地址用,会得到 404。

运行环境

  • Python 环境需要安装 openai 官方 SDK。
  • Node.js 环境需要安装 openai 包,并且运行环境要支持 for await 异步迭代(Node 10 及以上均可)。
  • 不想装 SDK 的话,用系统自带的 curl 就足够验证连通性。

本文示例统一使用 anthropic/claude-sonnet-4.6 这个模型名。模型清单和可用性会变化,实际接入前请以官网当前的模型总览为准。

操作步骤

第一步:把密钥放进环境变量

示例代码里用的是 $SSY_API_KEY 这个占位符,它代表你从控制台复制出来的密钥。在 shell 里先导出:

export SSY_API_KEY="你的密钥"

这样做的好处是代码里不出现明文密钥,换机器或换账号时只改环境变量。生产环境建议用密钥管理服务注入,而不是写进 .env 文件后随代码一起分发。

第二步:用 Python 发起流式请求

Python 侧的核心是构造一个 OpenAI 客户端,把 base_url 指向胜算云的地址,然后调用标准的 chat.completions.create:

from openai import OpenAI

client = OpenAI(
    base_url="https://router.shengsuanyun.com/api/v1",
    api_key="$SSY_API_KEY",
)

try:
    completion = client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        messages=[{"role": "user", "content": "Which number is larger, 9.11 or 9.8?"}],
        temperature=0.6,
        top_p=0.7,
        stream=True,
    )
    for chunk in completion:
        if chunk.choices and chunk.choices[0].delta.content is not None:
            print(chunk.choices[0].delta.content, end="", flush=True)
    except Exception as e:
        print(f"Request failed: {e}")

几个细节值得说明:

  • stream=True 打开后,返回的不再是一个完整响应对象,而是一个可迭代的流。必须逐块消费,否则拿不到内容。
  • 每个 chunk 的结构是 choices[0].delta.content,不是 message.content。流式模式下 delta 才是增量字段。
  • 判断条件里同时检查了 chunk.choices 非空和 delta.content 不为 None。有些 chunk 只携带角色信息或结束标记,内容字段为空,直接拼接会报错。
  • print 的 end="" 与 flush=True 让输出逐字刷新,否则终端会攒一大块才显示,看起来像卡住了。
  • 整个调用包在 try/except 里,网络中断、鉴权失败、额度不足都会在这里被捕获。

第三步:用 Node.js 发起同样的请求

JavaScript 版本逻辑一致,只是流式消费换成了 for await:

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://router.shengsuanyun.com/api/v1",
  apiKey: "$SSY_API_KEY",
});

async function main() {
  const stream = await openai.chat.completions.create({
    model: "anthropic/claude-sonnet-4.6",
    messages: [{ role: "user", content: "Which number is larger, 9.11 or 9.8?" }],
    temperature: 0.6,
    top_p: 0.7,
    stream: true,
  });

  for await (const chunk of stream) {
    if (chunk.choices[0].delta.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }
  }
  console.log("\n[chat complete]");
}

main();

注意配置项名是 baseURL(驼峰),不是 Python 里的 base_url。写错的话 SDK 会静默回退到默认的 OpenAI 地址,然后因为密钥不匹配而报鉴权错误,排查起来很费时间。另外 process.stdout.write 不换行,正好适合流式输出;最后的 console.log 用来在结束时补一个换行并打印完成标记。

第四步:用 curl 验证连通性

在写代码之前,先用 curl 确认密钥和地址是对的,可以省掉大量「到底是网络问题还是代码问题」的纠结:

API_KEY="$SSY_API_KEY"
BASE_URL="https://router.shengsuanyun.com/api/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.6"

curl -s -X POST "$BASE_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [{"role": "user", "content": "Which number is larger, 9.11 or 9.8?"}],
    "temperature": 0.6,
    "top_p": 0.7,
    "stream": true
  }'

这里有两个容易出错的点。第一,Authorization 头必须是 Bearer 加一个空格再加密钥,少了空格会返回 401。第二,Content-Type 必须是 application/json,否则服务端无法解析请求体。因为开了 stream: true,curl 会持续输出以 data: 开头的行,最后以 data: [DONE] 结束——看到这个标记就说明链路完全通了。

第五步:调整生成参数

示例里用了两个采样参数,理解它们的作用有助于得到稳定输出:

参数示例值作用
modelanthropic/claude-sonnet-4.6指定要调用的模型,切换模型只改这一项
messages单条 user 消息对话历史,按 role 与 content 组织
temperature0.6控制随机性,值越高输出越发散
top_p0.7核采样阈值,与 temperature 配合控制候选范围
streamtrue是否以流式增量返回结果

示例中的具体数值只是演示,不代表推荐值。不同任务对温度和采样策略的要求差别很大,需要按实际效果调整。各参数的完整定义与取值范围,请以官网当前的 API 参考为准。

一个完整示例

下面把前面的步骤串成一个可以直接运行的最小脚本。它做四件事:从环境变量读密钥、构造客户端、发起流式请求、把增量内容实时打印出来并在结束时给出提示。

import os
from openai import OpenAI

api_key = os.environ.get("SSY_API_KEY")
if not api_key:
    raise SystemExit("请先设置 SSY_API_KEY 环境变量")

client = OpenAI(
    base_url="https://router.shengsuanyun.com/api/v1",
    api_key=api_key,
)

try:
    stream = client.chat.completions.create(
        model="anthropic/claude-sonnet-4.6",
        messages=[
            {"role": "system", "content": "你是一个简洁的技术助手。"},
            {"role": "user", "content": "用三句话解释什么是流式响应。"},
        ],
        temperature=0.6,
        top_p=0.7,
        stream=True,
    )

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

    print("\n[完成]")

except Exception as e:
    print(f"\n请求失败: {e}")

运行前先执行 export SSY_API_KEY="你的密钥",然后 python script.py。如果终端里逐字出现回答内容,最后打印 [完成],说明整条链路已经打通。之后要换模型,只改 model 那一行的值;要换任务,只改 messages 的内容。Base URL 和密钥保持不变。

这个脚本相比前面的演示多了两处改进:一是启动时检查环境变量是否存在,避免拿着空字符串去请求然后收到一个语焉不详的 401;二是把 delta 的判空拆成两步,先确认 choices 非空,再确认 delta.content 有值,这样对返回结构的假设更少,遇到只带元信息的 chunk 也不会崩。

注意事项

密钥与额度

  • 创建密钥时要留意账户的 RPM 与 TPM 限制。这两个值直接决定你能跑多高的并发,超出后请求会被拒绝。具体额度以控制台显示和官网当前信息为准。
  • 密钥泄露等同于账号被他人使用,务必妥善保管,不要硬编码进代码或提交到版本库。
  • 计费规则、免费额度、充值方式等会随时间调整,接入前请查阅官网当前的账号与计费说明。

接口层面的常见问题

  • 404 找不到路径:多半是把 Base URL 当成了完整请求地址。SDK 用 https://router.shengsuanyun.com/api/v1,curl 用 https://router.shengsuanyun.com/api/v1/chat/completions。
  • 401 鉴权失败:检查 Bearer 后面是否有空格、密钥是否复制完整(首尾空格也算错)、环境变量是否真的导出到了当前 shell。
  • 流式输出为空:确认读的是 delta.content 而不是 message.content,并且对空值做了判断。
  • 请求超时或中断:流式请求持续时间较长,客户端和服务端之间的中间层(代理、网关)可能有空闲超时设置,需要相应放宽。

模型与路由

  • 平台会根据请求内容自动路由到最优模型。这意味着即使你指定了某个模型名,实际行为也可能受路由策略影响,对结果一致性要求极高的场景需要自行验证。
  • 模型名称、可用模型列表、各模型的上下文长度与定价都会变化,不要把它们写死在文档或配置里当作长期约定,以官网当前的模型总览为准。
  • 所有兼容接口共用同一个 Base URL 和 API Key,切换模型只需改 model 字段——这也是统一入口相比逐个对接各家 SDK 最直接的价值。

错误排查顺序

遇到问题时按这个顺序排查效率最高:先用 curl 验证密钥与地址是否可用;再用官方 SDK 跑最小示例,排除自己封装的干扰;最后才回到业务代码里检查参数拼装、流式消费和异常处理。把问题范围一层层缩小,比在完整业务代码里盲找要快得多。各类错误码的具体含义,请对照官网当前的 API 错误代码说明。