全部教程
本页目录
先说结论#
你需要的东西只有三样:
| 你要的 | 从哪来 | 长什么样 |
|---|---|---|
| 接口地址 | 控制台文档 | 形如 https://xxx/v1 |
| 密钥 | 控制台创建 | 一长串字符,只显示一次 |
| 模型 ID | 模型广场 | 形如 deepseek-chat,每家的名字不一样 |
把这三样填进任何支持 OpenAI 接口的工具,就算接好了。不需要改代码,不需要装 SDK 才能开始。
为什么推荐中转站而不是一个个去官方注册
一个 key 通多家模型,换模型不用换账单;国内直连不用折腾网络;按量计费,试错成本低。代价是多一层转发,极少数场景会有几十毫秒的额外延迟。
十分钟跑通#
第一步:注册并完成实名#
手机用相机对着下面这张图,或者在电脑上点这个链接:诸葛智算注册入口。走这条路注册会自动绑定站长渠道,活动折扣按站内算。

国内平台按规需要实名,这一步绕不过去,准备身份证即可。
注册后先在站内找「模型广场」和「文档」两个入口,后面要用。
第二步:创建密钥#
在控制台的「API 密钥」页面新建一个。两个习惯,从第一天就养成:
- 一个用途一个 key。桌面端、脚本、群机器人分开建。哪天某个泄露了,只吊销那一个。
- 创建后立刻粘贴到密码管理器。大多数平台只完整显示一次。
第三步:用 curl 验证#
不用装任何东西,终端里直接跑。把三个尖括号里的内容换成你自己的:
export ZHUGE_KEY="<你的key>"
export ZHUGE_BASE="https://zhugeai.cn/v1"
export MODEL="<模型广场里复制的模型ID>"
curl -s "$ZHUGE_BASE/chat/completions" \
-H "Authorization: Bearer $ZHUGE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$MODEL"'",
"messages": [{"role": "user", "content": "只回复两个字:通了"}],
"max_tokens": 20
}'验收标准:返回的 JSON 里有 choices[0].message.content,内容是「通了」或者类似的回答。
如果这一步就报错,先别往下走,直接看本文最后一节「报错对号入座」。
第四步:固定下来,别再手打#
把变量写进 ~/.zshrc(或 ~/.bashrc),新开终端就能用。不要把 key 写进任何会被提交的文件。
# ~/.zshrc
export ZHUGE_KEY="<你的key>"
export ZHUGE_BASE="https://zhugeai.cn/v1"source ~/.zshrc && echo "${ZHUGE_KEY:0:6}..." # 只回显前 6 位,确认加载了接到你自己的工具里#
Python(官方 openai 库)#
中转站兼容 OpenAI 协议,所以官方 SDK 直接能用,只改 base_url:
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ZHUGE_KEY"],
base_url=os.environ["ZHUGE_BASE"],
)
resp = client.chat.completions.create(
model=os.environ["MODEL"],
messages=[
{"role": "system", "content": "你是简洁的中文助手。"},
{"role": "user", "content": "用一句话解释什么是 token"},
],
)
print(resp.choices[0].message.content)Node.js#
import OpenAI from 'openai'
const client = new OpenAI({
apiKey: process.env['ZHUGE_KEY'],
baseURL: process.env['ZHUGE_BASE'],
})
const res = await client.chat.completions.create({
model: process.env.MODEL,
messages: [{ role: 'user', content: '你好' }],
})
console.log(res.choices[0].message.content)各种客户端(WorkBuddy / DSH / Hermes / 桌宠)#
它们要的都是同一组东西:接口地址 + 密钥 + 模型名。区别只在「填在哪」。
- WorkBuddy:设置里找「模型服务 / API」相关项,见 WorkBuddy 教程
- DSH:profile 的 provider 配置,见 DSH 教程
- Hermes:
hermes setup model或config.yaml的providers,见 Hermes 教程 - 大肥鱼桌宠:首次启动会让你填,见 大肥鱼教程
模型 ID 别照抄网上的
每个平台的模型命名都不一样,同一个月底也可能改名。永远从你控制台的模型广场复制,不要用教程里的示例。看到 model not found,九成是这里错了。
怎么不花冤枉钱#
按量计费的意思是:你不注意,它就一直烧。三个立刻能做的动作:
1. 按任务分级用模型#
| 任务 | 用哪档 | 理由 |
|---|---|---|
| 分类、打标签、纠错 | 小模型 | 一次几分钱,够用 |
| 日常问答、写草稿 | 中档 | 性价比区间 |
| 长文推理、代码重构 | 大模型 | 只在这类任务上开 |
同一个产品里混着用,是最省的做法。别所有请求都打最贵的那个。
2. 能缓存就缓存#
系统提示词、固定知识、工具说明——这些每次都一样。支持 prompt 缓存的模型,命中后单价通常低一个量级。把「不变的」放前面,「变的」放后面,是缓存命中的前提。
3. 每个项目单独限额#
控制台里给 key 设日限额。写脚本的时候也会更小心——限额一到就失败,比月底看到账单好。
一个反直觉的经验
大多数人的成本不在模型单价,在重复调用。同一个问题问五遍、把整篇文档反复塞进上下文,比换更贵的模型烧得多。先优化调用次数,再优化单价。
报错对号入座#
| 状态码 | 大概率原因 | 怎么修 |
|---|---|---|
401 | key 错、过期、或复制时带了空格/换行 | 重新复制,注意别带引号;确认 Bearer 后面有一个空格 |
403 | 没实名、没开通该模型、或余额不足 | 看控制台提示,补实名或充值 |
404 | 接口路径错(少 /v1)或模型 ID 不存在 | 路径用文档给的原文;模型名从模型广场复制 |
429 | 触发限流或额度上限 | 降并发、加退避重试;看是不是设了日限额 |
5xx | 上游模型厂商抖动 | 等几秒重试;连续失败就换模型 ID 试 |
| 返回空内容 | max_tokens 太小,或触发了内容过滤 | 调大 max_tokens,换个问法 |
排查顺序建议固定成:先 curl,再 SDK,最后你自己的代码。curl 通了说明 key 和网络没问题,问题在后两层;curl 不通就别在代码里找。
安全三条#
- key 不进仓库。
.env加进.gitignore,仓库里只放.env.example占位。 - 截图先打码。控制台页面、终端回显、报错信息里都可能带 key 的前缀和后缀。
- 泄露立刻吊销。别抱侥幸,重新建一个只要十秒。
# .gitignore
.env
.env.*
!.env.example验收清单#
这五条都打勾,再去看下一篇。否则后面每一篇都会卡在同一个地方。