AB
AB
AiBoss

All Categories

Tutorials

SiliconFlow

Tutorials

用 SiliconFlow API 调用大模型并接入 ChatBox

从注册 SiliconFlow、在模型广场挑选模型，到用 Python 发送第一个对话请求，再把 API 接入 ChatBox 客户端，一步步跑通文本生成链路。文中给出可复用的请求结构、参数说明与常见报错排查方向，并提示密钥保管、免费额度与计费信息以官网当前页面为准。

SiliconFlow 是一个面向开发者的大模型云服务平台，把 Llama、Stable Diffusion 等一批开源模型托管在云端，通过统一的 HTTP 接口对外提供文本、图像、语音、视频等多模态生成能力。它的价值在于省掉自建推理集群这一步：你不需要准备显卡、不需要部署推理框架，注册拿到密钥后就能直接发请求。这篇教程面向想快速把大模型能力接进自己程序或客户端的开发者，重点讲清两件事——怎样用 Python 调用 SiliconFlow 的对话接口，以及怎样把同一个密钥配置到 ChatBox 这类图形客户端里。如果你只是想先比较一下站内可用的工具，可以从 SiliconFlow 这一条目入手，再回到本文按步骤操作。

需要先说明的是，平台上的模型清单、免费额度、计费单价和接口地址都属于会变动的信息，本文只讲调用方法与请求结构，具体数值请以官网控制台和文档当前展示的内容为准。

准备工作

账号与实名认证

使用 SiliconFlow 的第一步是注册账号。注册入口在平台首页，填写基本信息即可完成账号创建。注册之后平台通常会赠送一定额度的免费 Token 供体验，具体数量以注册页面和控制台显示为准，不要以任何第三方文章里的数字为准。

部分功能（尤其是正式调用与付费资源）需要完成实名认证。认证流程在控制台内发起，按页面提示提交材料即可。如果只是先做小规模试验，可以先确认免费额度是否已经到账，再决定是否立刻认证。

获取 API 密钥

登录后进入控制台，找到 API 密钥管理页面，新建一个密钥。密钥只在创建时完整显示一次，请立刻复制并保存到安全的位置。后续所有请求都靠这个字符串做身份识别，一旦泄露，他人可以直接消耗你的额度。

建议按用途拆分密钥：本地实验用一个，线上服务用另一个。这样某一支泄露时可以单独吊销，不影响其他调用方。

选择模型

控制台里的「模型广场」列出了当前可调用的模型，每个模型条目会标注模型标识（也就是请求里 model 字段要填的字符串）、上下文长度、是否支持多模态、以及计费方式。先把要用的模型标识记下来，后面写代码时直接填进去。

素材中提到，部分参数量较小的模型（9B 以下）可以永久免费调用，适合用来做联调和压力测试。但免费模型的清单会调整，实际以模型广场页面的标注为准。

本地环境

Python 侧只需要一个能发 HTTP 请求的环境。推荐 Python 3.8 及以上版本，并安装 requests 库：

pip install requests

如果打算用图形客户端验证，另外准备 ChatBox 桌面版，从它的官方发布渠道下载安装最新版本即可。

操作步骤

第一步：确认接口地址与鉴权方式

SiliconFlow 的对话接口是一个 HTTP POST 端点，采用 Bearer Token 鉴权。请求头里需要带三项：

  • accept: application/json，声明期望返回 JSON。
  • content-type: application/json，声明请求体是 JSON。
  • authorization: Bearer <你的 API 密钥>，注意 Bearer 与密钥之间有一个空格。

接口地址（base URL）请从控制台的接口文档页复制，不要凭记忆手写。不同模型可能挂在不同的路径下，图像、语音、视频类接口与文本对话接口的路径也不相同。

第二步：构造对话请求体

文本对话接口的请求体至少包含三个字段：

字段类型说明
model字符串模型标识，取自模型广场，例如某个具体的开源模型名称
messages数组对话消息列表，每条消息含 role 与 content
stream布尔是否流式返回。设为 false 时一次性拿到完整结果，便于调试

messages 里的 role 常见取值是 system、user、assistant。单轮问答只需要一条 user 消息；多轮对话则把历史消息按顺序全部带上，模型据此理解上下文。

第三步：发送请求并解析返回

返回体是 JSON，正文内容位于 choices[0].message.content。下面是一个可以直接运行的最小脚本，把密钥和模型标识换成你自己的即可：

import os
import requests

API_KEY = os.getenv("SILICONFLOW_API_KEY", "")
BASE_URL = "<从控制台复制的对话接口地址>"
MODEL = "<模型广场中的模型标识>"

payload = {
    "model": MODEL,
    "messages": [
        {"role": "user", "content": "用三句话解释什么是推理加速引擎。"}
    ],
    "stream": False
}

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {API_KEY}"
}

response = requests.post(BASE_URL, json=payload, headers=headers, timeout=60)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

几个细节值得注意。第一，密钥通过环境变量读取，不要硬编码进源码，避免随代码一起提交到版本库。第二，timeout 一定要设，长文本生成可能耗时较久，但完全不设超时会让程序在异常情况下无限挂起。第三，raise_for_status() 会在 4xx / 5xx 时抛异常，比直接取字段更早暴露问题。

第四步：封装成可复用的调用函数

把请求逻辑包进一个类或函数，后续换模型、加系统提示词都只改一处。下面这个封装保留了 stop 参数的位置，用于在返回文本中截断到指定停止词：

import os
import requests

API_KEY = os.getenv("SILICONFLOW_API_KEY", "")
BASE_URL = "<从控制台复制的对话接口地址>"


class SiliconFlowClient:
    def __init__(self, api_key: str = API_KEY, base_url: str = BASE_URL):
        self.api_key = api_key
        self.base_url = base_url

    def chat(self, prompt: str, model: str, system: str = None, stop: list = None) -> str:
        messages = []
        if system:
            messages.append({"role": "system", "content": system})
        messages.append({"role": "user", "content": prompt})

        payload = {
            "model": model,
            "messages": messages,
            "stream": False
        }
        headers = {
            "accept": "application/json",
            "content-type": "application/json",
            "authorization": f"Bearer {self.api_key}"
        }
        resp = requests.post(self.base_url, json=payload, headers=headers, timeout=60)
        resp.raise_for_status()
        text = resp.json()["choices"][0]["message"]["content"]

        if stop:
            for token in stop:
                idx = text.find(token)
                if idx != -1:
                    text = text[:idx]
        return text


if __name__ == "__main__":
    client = SiliconFlowClient()
    print(client.chat("写一段 100 字的产品简介。", model="<模型标识>"))

封装之后，切换模型只需要改 model 参数，做 A/B 对比测试会方便很多。

第五步：接入 ChatBox 客户端

如果不想写代码，可以用 ChatBox 这类桌面客户端直接对话。配置流程如下：

  1. 下载并安装最新版 ChatBox。
  2. 打开设置，把「Model provider」（模型提供方）设为「SiliconFlow API」。
  3. 在 API 密钥输入框里粘贴控制台创建的密钥。
  4. 在模型下拉列表中选择要使用的模型。
  5. 保存设置，回到对话界面发一条测试消息，确认能正常返回。

如果客户端里没有预置 SiliconFlow 选项，可以退一步用「自定义 OpenAI 兼容接口」的方式配置：填入控制台给出的接口地址和密钥，模型名手动填写。配置完成后同样先发一条短消息验证连通性，再投入正式使用。

一个完整示例

下面把前面的步骤串起来，做一个带系统提示词的多轮对话脚本。它会先设定角色，再连续问两个问题，第二个问题依赖第一个问题的上下文。

import os
import requests

API_KEY = os.getenv("SILICONFLOW_API_KEY", "")
BASE_URL = "<从控制台复制的对话接口地址>"
MODEL = "<模型广场中的模型标识>"

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": f"Bearer {API_KEY}"
}

messages = [
    {"role": "system", "content": "你是一名技术文档编辑，回答简洁，不使用营销话术。"},
    {"role": "user", "content": "什么是推理引擎？"}
]

resp = requests.post(
    BASE_URL,
    json={"model": MODEL, "messages": messages, "stream": False},
    headers=headers,
    timeout=60
)
resp.raise_for_status()
answer1 = resp.json()["choices"][0]["message"]["content"]
print("第一轮：", answer1)

messages.append({"role": "assistant", "content": answer1})
messages.append({"role": "user", "content": "那它和普通推理框架的主要区别是什么？"})

resp2 = requests.post(
    BASE_URL,
    json={"model": MODEL, "messages": messages, "stream": False},
    headers=headers,
    timeout=60
)
resp2.raise_for_status()
print("第二轮：", resp2.json()["choices"][0]["message"]["content"])

运行前先导出密钥：

export SILICONFLOW_API_KEY="你的密钥"

在 Windows 的命令行里对应写法是 set SILICONFLOW_API_KEY=你的密钥，PowerShell 里是 $env:SILICONFLOW_API_KEY="你的密钥"。脚本跑通后，你会看到两段回答，第二段能正确承接第一段的内容，说明多轮上下文传递正常。

这个骨架可以直接扩展：把 messages 换成从数据库读出的历史记录，就得到一个带记忆的问答服务；把 stream 改成 true 并按行解析返回流，就能实现逐字输出的打字机效果。

注意事项

密钥安全

API 密钥等同于账号的调用凭证。不要把密钥写进前端代码、公开仓库或截图里。如果怀疑泄露，立刻在控制台吊销并重建。生产环境建议在服务端做一层代理，由服务端持有密钥，客户端只与自己的后端通信。

额度与计费

新账号的免费 Token 额度、各模型的单价、免费模型的适用范围都会调整，务必以控制台当前展示为准。免费额度用尽后调用会失败，因此上线前应确认账户余额与计费方式，并在代码里对额度不足类错误做兜底处理。

常见报错方向

  • 401 未授权：密钥拼写错误、密钥已被吊销，或 authorization 头里漏了 Bearer 前缀。
  • 404 找不到路径：接口地址填错，或把文本接口地址用在了图像、语音类模型上。
  • 400 参数错误：model 填的标识不在模型广场清单里，或 messages 结构不符合要求。
  • 超时：长文本生成耗时较长，适当调大 timeout，或改用流式返回。

模型能力差异

不同模型的上下文长度、是否支持多模态输入、输出风格差别很大。同一个提示词在不同模型上的效果可能完全不同，选型时建议用同一批测试用例横向对比，而不是只看参数量。素材提到平台覆盖文本、图像、语音、视频四类生成任务，但每类任务对应的接口路径和参数结构并不通用，切换任务类型时要重新查阅对应接口的字段说明。

关于私有化与微调

平台面向企业用户提供私有化部署方案，支持上传自有数据做模型微调，并配套持续集成与部署流程。这部分属于企业级能力，开通方式、数据格式要求和费用都需要与平台侧确认，不在本文的 API 调用范围内。

Back