THU算力券：大模型 API 一键接入

概述

本 Skill 用于完成大模型 API 的接入配置，尤其适配清华算力券场景（并行智算云 MaaS 平台）。核心流程：确认端点 → 验证密钥 → 搭建零依赖调用环境 → 实测验证 → 交付用法说明 →（可选）注册进 WorkBuddy 模型选择器。

适用平台：任何 OpenAI 兼容协议的 API（并行智算云 MaaS、智谱 AI、DeepSeek、阿里百炼等）。

算力券用户说明：清华算力券在并行智算云平台使用，用户拿到的是平台 API 密钥（sk- 开头），可调用平台聚合的 GLM/DeepSeek/Qwen/Kimi/MiniMax 等近百个模型。

常见疑问预答：并行智算云是"模型超市"不是模型厂商，/models 返回的列表里不会有名字带"并行/Paratera"的模型——GLM/DeepSeek/Qwen 等第三方模型就是"并行云的模型"。若用户问"为什么不显示并行云的模型"，先解释这一点，再确认用户真正想要的是本地脚本可用，还是 WorkBuddy 模型下拉框里可选（见第七步）。

工作流程

第一步：收集信息

向用户确认以下四项：

1. API 平台（平台名称 + 官网；清华算力券用户默认为"并行智算云 https://ai.paratera.com"，无需追问）
2. API 密钥（完整密钥字符串）
3. 想用的模型（具体模型名，或"帮我推荐"）
4. 密钥用途（开发项目调用 / 给 WorkBuddy 客户端用 / 两者都要；用户没说则默认两者都配好）

如果用户只给了密钥和平台名，主动查官方文档确定 base_url。如果用户提到"算力券"但没给平台，默认按并行智算云处理。

第二步：确认端点

查该平台官方文档获取 OpenAI 兼容端点。常见平台端点速查：

端点验证容错：如果主端点连接失败（超时/DNS 解析失败/HTTP 5xx），先尝试备用端点再报错；都失败才提示用户检查网络环境（内网/防火墙）。

第三步：验证密钥

用 GET 请求访问 {base_url}/models，请求头带 Authorization: Bearer {密钥}：

• HTTP 200：密钥有效。保存返回的模型 ID 列表，供用户选择。
• HTTP 401：密钥错误/过期/平台不对。立即停止，把错误信息原样给用户，提示去平台控制台重新生成密钥。不要继续后续步骤。
• HTTP 403：密钥有效但无权限。提示用户检查：① 账户算力券额度是否用完；② 想用的模型是否需要单独开通。
• HTTP 429：请求限流，等待 30 秒重试一次。
• 网络层错误（Timeout/ConnectionError）：提示用户当前网络可能无法访问平台（内网/防火墙），建议换网络重试。

注意：密钥验证通过 ≠ 调用成功。额度用完时密钥依然有效（/models 返回 200），但 chat 调用会失败——如果后续 chat 步骤报 403/429，优先引导用户去平台控制台查额度。

第四步：搭建调用环境

在工作区创建 llm/ 目录，包含三个文件，全部用 Python 标准库实现（urllib + json），不安装任何第三方依赖：

4.1 .env 文件

# API 配置
API_KEY=这里填密钥
DEFAULT_MODEL=模型ID
BASE_URL=https://平台域名/v1

4.2 llm_client.py 文件

客户端封装类，至少包含：

• __init__()：自动读取同目录 .env，支持参数覆盖（api_key / model / base_url）
• chat(messages, temperature=0.7, max_tokens=2048, stream=False)：同时兼容字符串和消息数组两种输入（用户可能直接传 "你好"，也可能传 [{"role": "user", "content": "你好"}]，内部统一转换），返回字符串
• stream_chat(messages, temperature=0.7, max_tokens=2048)：流式对话，逐段 yield 文本
• list_models()：返回平台支持的模型 ID 列表

构造函数读取 .env 的优先级：API_KEY → DEFAULT_MODEL → BASE_URL。

密钥校验：如果密钥为空或包含占位符文本（如"在这里"），抛出 ValueError 提示用户填写。

空正文自检：如果响应的 content 为空且 reasoning_content 非空，抛出带明确说明的异常："思考型模型把 token 用在了推理上，请将 max_tokens 提高到 4096"，不要让用户面对空字符串自己猜原因。

4.3 test_llm.py 文件

连通性测试脚本：

from llm_client import LLMClient

client = LLMClient()
print(f"模型: {client.model}")
reply = client.chat("用一句话回答：1+1等于几？", max_tokens=2048)
print(f"[成功] 回复: {reply}")

第五步：实测验证

运行测试脚本，验证：
1. 普通调用正常返回
2. 流式调用正常输出

第六步：交付说明

测试通过后，给用户提供：

1. 最简用法（三行代码，示例同时演示字符串输入：client.chat("你好")）
2. 模型切换方法（改 .env 或传参）
3. 可用模型清单（从 list_models() 获取，按系列分组展示，注明模型名严格区分大小写）

交付时主动询问用户是否还需要"把模型接进 WorkBuddy 模型选择器"（很多用户配置完本地脚本后，期望在 WorkBuddy 界面的模型下拉框里直接选这些模型——这是最高频的后续需求，不要等用户自己发现缺失）。

第七步（可选）：注册进 WorkBuddy 模型选择器

如果用户需要，编辑 ~/.workbuddy/models.json（JSON 数组，支持热加载，约 1 秒防抖生效；若界面未刷新，提示重启 WorkBuddy 或重新打开下拉框）。每个模型一个对象，schema 如下（字段名必须完全一致）：

{
  "id": "GLM-5.3",
  "name": "并行·GLM-5.3",
  "vendor": "Paratera",
  "url": "https://ai.paratera.com/v1/chat/completions",
  "apiKey": "sk-xxx",
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": true,
  "useCustomProtocol": false
}

字段说明：

注册建议：默认接入 8~10 个覆盖不同用途的模型（省钱 Flash 版、高质量旗舰、深度推理、长文本），不要全量灌入 93 个。写入前必须先读取现有 models.json 并合并追加（保留用户已有配置，绝不覆盖），写入后实测一次 chat 调用验证（HTTP 200 + 正文非空）。

密钥安全提醒：models.json 是明文密钥，交付时必须告知用户两点：① 不要把该文件截图/分享；② 如需更安全的方式，可改用环境变量引用（若平台支持 ${VAR} 语法）或后续平台提供加密存储时迁移。

关键注意事项

1. 思考型模型（如 GLM-5.x 系列、DeepSeek-R1/Thinking 系列、ERNIE-5.0-Thinking-Preview）会先消耗 token 思考再输出正文，max_tokens 必须给到 2048 以上（建议 4096），否则返回的 content 为空。如果遇到空回复，先检查是否这个原因——思考内容在返回的 reasoning_content 字段里。实测：GLM-5.3-Flash 在 max_tokens=64 时正文为空，2048 起正常（60 个 reasoning tokens + 正常正文）。

2. 模型名区分大小写，必须和 /models 接口返回的 ID 完全一致（如 DeepSeek-V3.2 不是 deepseek-v3.2）。

3. 密钥安全：密钥只写入 .env / models.json，不硬编码进代码、不写进任何会被分享的文件；测试打印密钥时只显示前 8 位。.env 必须加入 .gitignore。

4. "验证通过"与"调用成功"是两回事：/models 返回 200 只说明密钥格式有效；额度用完、模型未开通等问题只在 chat 调用时暴露。交付前必须完成一次真实 chat 调用验证。

5. 常见用户疑问："为什么不显示并行云的模型？"——并行智算云是模型聚合平台不是模型厂商，/models 列表里不会有带"并行"前缀的模型名，GLM/DeepSeek/Qwen 等就是平台聚合的模型。

6. 回滚指令：如果用户说"回滚/不要配置了"，立即停止操作并清理已创建的文件（llm/ 目录及 models.json 中新增的条目），不做任何辩解。

参考资源

references/api_platforms.md

常见大模型 API 平台的端点、认证方式和注意事项文档。当需要确认平台信息时加载。

scripts/ 目录

本 Skill 不包含预置脚本——每次接入的密钥、模型、平台都不同，脚本由 WorkBuddy 在运行时按上述流程动态生成。