
百灵大模型
用百灵大模型 Ling-1T 的兼容接口接入对话与多轮上下文
百灵大模型(Ling-1T)是蚂蚁集团推出的对话平台,支持免注册网页体验,并为开发者提供 OpenAI 兼容接口。本文说明如何完成账号与密钥准备、配置 Base URL 与 Bearer 认证、发起首次对话请求、保持多轮上下文、调节温度与重复惩罚等参数,并给出一个可跑通的完整调用示例与常见注意事项。
百灵大模型是蚂蚁集团推出的对话平台,底层模型为 Ling-1T。它面向两类使用者:一类是只想快速试一试大模型效果的普通用户,可以直接在网页对话框里输入问题拿到回复,不需要注册;另一类是要把模型接进自己系统的开发者,平台提供了与 OpenAI 接口形式兼容的调用方式,配置好终端地址和认证信息后,就能用常见的 SDK 或 HTTP 请求发起对话。如果你正在找一个可以先用网页验证效果、再平滑过渡到代码调用的模型服务,可以把它和本站的 百灵大模型 条目对照着看。本文讲的是开发者侧那条路径:从拿到密钥到跑通一次带上下文的对话请求。
准备工作
在写第一行代码之前,需要把下面几件事确认清楚。这些是调用能否成功的前置条件,缺一项都会在请求阶段报错。
账号与密钥
- 注册账号:开发者调用需要先注册平台账号。网页端的免注册体验和 API 调用是两条不同的入口,不要以为网页能直接对话就等于拿到了接口权限。
- 完成支付宝绑定:账号注册后需要完成支付宝绑定,这是开通开发者能力的一环。绑定流程在平台账号设置里完成,具体入口以官网当前页面为准。
- 获取专属 API 密钥:绑定完成后在控制台生成自己的 API 密钥。这个密钥等同于身份凭证,不要写进前端代码、不要提交到公开仓库,也不要贴到聊天群里。
接口地址与认证方式
平台提供的是 OpenAI 兼容接口,两个关键参数固定如下:
| 项目 | 取值 |
|---|---|
| Base URL(终端地址) | api.tbox.cn/api/llm/v1 |
| 认证方式 | Bearer Token,即请求头 Authorization: Bearer <你的密钥> |
因为路径结构与 OpenAI 的 /v1 约定一致,所以大多数支持自定义 Base URL 的 OpenAI 客户端库可以直接指向这里,只需要把密钥换成平台签发的那个。这一点在后面的示例里会体现。
额度与上下文长度
平台对开发者提供每日免费调用额度,用于中小规模的开发与测试;模型支持的最高上下文长度为 128K token。额度数值、是否调整、超出后的计费方式都属于会变动的信息,动手前请以官网当前公布的说明为准,不要按旧文章里的数字做容量规划。
环境准备
示例使用 Python,需要能运行 Python 3 的环境,并安装 OpenAI 官方 Python 库。用虚拟环境隔离依赖是常规做法:
python -m venv venv
source venv/bin/activate
pip install openai
Windows 下激活命令是 venv\Scripts\activate。库的版本会随时间变化,安装最新稳定版即可,本文不锁定具体版本号。
操作步骤
第一步:把密钥放进环境变量
不要在源码里硬编码密钥。先设置环境变量,代码从环境里读取:
export LING_API_KEY="你的密钥"
Windows PowerShell 用 $env:LING_API_KEY="你的密钥"。生产环境应使用密钥管理服务注入,而不是写进 shell 配置文件。
第二步:初始化客户端
用 OpenAI 库初始化客户端,把 base_url 指向平台的终端地址,api_key 从环境变量读取:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["LING_API_KEY"],
base_url="https://api.tbox.cn/api/llm/v1",
)
注意 Base URL 要带上协议头,并且以 /v1 结尾。少写协议头或者多写一层路径,都会导致请求打到错误的位置。
第三步:发起一次单轮对话
最小的一次调用只需要一个用户消息:
resp = client.chat.completions.create(
model="ling-1t",
messages=[
{"role": "user", "content": "用三句话解释什么是向量数据库"},
],
)
print(resp.choices[0].message.content)
返回结构与 OpenAI 的对话补全接口一致:正文在 choices[0].message.content 里。如果客户端库报模型名不存在,说明模型标识需要按平台控制台当前列出的名称填写,不要照抄示例里的字符串。
第四步:保持多轮上下文
接口本身是无状态的,所谓「多轮对话」是把历史消息一起带上去。做法是维护一个消息列表,每轮把用户输入追加进去,再把模型回复也追加进去,下次请求时整段发送:
messages = [
{"role": "system", "content": "你是一名严谨的技术文档编辑,回答简洁。"},
]
def chat(user_text):
messages.append({"role": "user", "content": user_text})
resp = client.chat.completions.create(
model="ling-1t",
messages=messages,
)
reply = resp.choices[0].message.content
messages.append({"role": "assistant", "content": reply})
return reply
print(chat("什么是 Bearer Token?"))
print(chat("它和 Basic 认证有什么区别?"))
第二次调用能理解「它」指代什么,靠的就是列表里保留的第一轮问答。这里有两个实践要点:一是 system 消息放在列表最前面,用来约束回答风格;二是列表会随轮次增长,长会话要主动裁剪,否则会撞上 128K token 的上下文上限。
第五步:调节生成参数
平台支持通过参数调节输出效果,常用的两个是温度值和重复惩罚。温度越低输出越稳定、越接近确定性;温度越高越发散。重复惩罚用于抑制模型反复说同一句话。示例:
resp = client.chat.completions.create(
model="ling-1t",
messages=[{"role": "user", "content": "给这个函数写一段 docstring"}],
temperature=0.3,
frequency_penalty=0.2,
)
参数名沿用 OpenAI 兼容接口的命名。不同场景的取值没有通用答案:抽取、改写、代码生成这类任务适合低温;头脑风暴、文案发散适合高温。建议先用默认值跑通,再针对具体任务小步调整,每次只改一个参数,便于判断效果变化来自哪里。
第六步:处理复合型输入
平台具备多模态信息处理能力,可以接收文本与图像等多元信息。具体到请求体里如何组织图像内容,取决于平台当前支持的字段格式,接入前请对照官网的接口说明确认,不要直接套用其他厂商的写法。如果只需要纯文本能力,跳过这一步即可。
一个完整示例
下面把前面的步骤串成一个可运行脚本:读取环境变量、初始化客户端、带 system 提示进行两轮对话、打印回复与 token 用量。保存为 ling_demo.py 后执行 python ling_demo.py。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["LING_API_KEY"],
base_url="https://api.tbox.cn/api/llm/v1",
)
messages = [
{"role": "system", "content": "你是一名中文技术文档编辑,回答控制在 200 字以内。"},
]
def ask(text):
messages.append({"role": "user", "content": text})
resp = client.chat.completions.create(
model="ling-1t",
messages=messages,
temperature=0.4,
frequency_penalty=0.1,
)
reply = resp.choices[0].message.content
messages.append({"role": "assistant", "content": reply})
usage = resp.usage
print(f"[tokens] prompt={usage.prompt_tokens} completion={usage.completion_tokens}")
return reply
if __name__ == "__main__":
print(ask("解释一下什么是幂等性。"))
print(ask("举一个 HTTP 接口里的例子。"))
运行后应当看到两段回复,以及每次调用打印出的 token 用量。第二段回复能接着第一段的话题举例,说明上下文传递生效。如果第一段就报认证错误,检查环境变量是否在当前 shell 生效;如果报连接错误,检查 Base URL 是否写全了协议头与 /v1。
把这个脚本改造成服务时,通常要做三件事:把 messages 从全局变量改成按会话 ID 存储;给请求加超时与重试;对返回内容做长度截断,避免单条回复过长挤占后续轮次的上下文预算。
注意事项
- 额度是会变的:每日免费 token 额度、模型可用性、是否收费,都以官网当前信息为准。做容量规划前先确认,不要按本文或旧文章里的数字估算。
- 上下文有上限:最高 128K token 是整段请求(含历史消息与 system 提示)的总和,不是单条消息的长度。长会话必须做裁剪或摘要,否则请求会被拒绝。
- 密钥泄露风险:密钥以 Bearer Token 形式放在请求头里,任何能抓包或读日志的环节都可能看到它。不要把密钥写进前端、日志、错误上报和代码仓库。
- 兼容不等于完全一致:接口形式与 OpenAI 对齐,但模型标识、多模态字段、部分可选参数的支持范围可能不同。遇到 4xx 错误时,先对照平台接口说明核对字段,而不是反复改代码逻辑。
- 网页体验与 API 是两条路径:网页端可以免注册直接对话,适合快速验证效果;API 调用需要注册、绑定并获取密钥。不要把网页端的可用性当成接口已开通。
- 输出需要校验:模型生成的内容可能包含事实错误或过时信息,用于面向用户的场景时应加人工复核或规则校验,尤其是涉及金额、医疗、法律等敏感领域的内容。