AB
AiBoss
チュートリアル

百灵大模型

チュートリアル

用百灵大模型 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 调用需要注册、绑定并获取密钥。不要把网页端的可用性当成接口已开通。
  • 输出需要校验:模型生成的内容可能包含事实错误或过时信息,用于面向用户的场景时应加人工复核或规则校验,尤其是涉及金额、医疗、法律等敏感领域的内容。