教程
HiAPI 上的 Gemini-4 Argon 与 Carbon:curl、Python 与可运行请求
一份实用集成指南,面向在 gemini-4-argon、gemini-4-carbon 和 gemini-4-carbon@vertex 之间做选择的开发者
本页内容
写代码之前先选定 Gemini-4 变体
任何 Gemini-4 集成的第一个决定不是 curl 还是 Python——而是你发送哪个模型 ID。在 HiAPI 上,gemini-4-argon、gemini-4-carbon 和 gemini-4-carbon@vertex 是三个不同的可路由目标,你在 model 字段中传入的字符串决定了由哪个后端来服务你的请求。提前选定它,可以省去调试一个本就无法工作的请求体的麻烦。
实践中的三个目标
gemini-4-argon—— 一个独立的 Gemini-4 变体,拥有自己的模型 ID。把它当作它自己的模型,而不是别名:它的行为、延迟特征和输出特性可能与 Carbon 不同。gemini-4-carbon—— HiAPI 标准路由下的默认 Carbon 目标。gemini-4-carbon@vertex—— 同一 Carbon 系列,但通过由 Vertex 支持的路由提供服务。@vertex后缀是模型 ID 本身的一部分,而不是一个单独的参数。
如何决定
从工作负载出发。如果你在广泛评估 Gemini-4,请对 gemini-4-argon 和 gemini-4-carbon 分别运行相同的提示词,并在定下来之前比较输出。如果你确实需要 Vertex 路由——比如因为它与你团队已经在运营的环境相匹配——那就直接以 gemini-4-carbon@vertex 为目标。
实际要点:这三个都使用相同的请求结构。选择变体只是改一行的事,因此你可以等到拥有一个可运行的请求之后再确定最终决定。如果你想先看模型卡片,请参见 gemini-4-argon 和 gemini-4-carbon。
本指南中的示例全程使用 gemini-4-carbon;要跟随任何变体操作,只需替换该 ID。
准备好凭据和基础 URL
在任何请求体变得重要之前,必须先确保三件事正确:基础 URL、API 密钥和鉴权头格式。大多数首次请求失败都出在这三者之一。
你需要什么
- 一个 API 密钥,来自你的 HiAPI 账户仪表板。把它当作机密——从环境变量加载,而不是粘贴到源文件中。
- HiAPI 基础 URL。 所有模型调用都发往同一主机;模型变体由
model字段选择,而不是由路径选择。 - 每个请求都要带两个头:
Authorization: Bearer $HIAPI_API_KEYContent-Type: application/json
设置你的环境
export HIAPI_API_KEY="your-key-here"
然后在写任何代码之前,验证你的 shell 能看到它:
echo "${HIAPI_API_KEY:0:4}..."
如果它没有打印任何内容,说明你的密钥未在当前 shell 中导出,每个请求都会因鉴权错误而失败。在这里修复它,而不是在你的客户端里修。
你将反复使用的请求结构
下面的每个示例都发送一个 JSON 请求体,其中包含一个 model 字符串和一个 messages 数组。这种结构在 curl 与 Python 之间、非流式与流式之间、以及模型变体之间都不会改变。保持它稳定,你就可以通过复制请求体来移植代码。
一个可运行的 curl 请求
下面是一个完整、可直接复制粘贴的非流式调用。在添加任何其他内容之前先运行它——这里请求通过就证明你的密钥、基础 URL 和请求头都正确。
curl -sS "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."}
]
}'
每个字段的作用
model—— 变体选择器。把它改成gemini-4-argon或gemini-4-carbon@vertex,无需其他任何改动即可命中不同目标。messages—— 一个有序数组。角色有system、user和assistant。如果你使用系统消息,请把它放在最前面。content—— 消息文本。对于简单的文本轮次,它是一个普通字符串。
阅读响应体
响应是一个 JSON 对象,包含模型的回复以及诸如 token 用量之类的元数据。由于这是非流式,整个请求体一次性到达,curl 在打印后退出。如果你得到一个可解析的 JSON 对象并带有消息回复,你的请求就是通的——后续所有内容都建立在这个基线之上。
一个快速的健全性检查:把输出通过 JSON 格式化器(| jq .)处理,这样响应结构就清晰可读,而不是一行长文本。
用 Python 发送同样的请求
Python 版本保持请求体完全一致——只有传输方式改变。使用 requests:
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."},
],
}
response = requests.post(
f"{base_url}/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
为什么这与 curl 调用完全对应
注意,payload 与上一节的 JSON 请求体逐字节相同。json= 参数会把它序列化并为你设置 Content-Type;请求头字典提供鉴权。模型、消息或角色都没有变化。
两个值得保持的习惯
- 设置超时。 没有超时的话,连接一旦停滞就会让你的进程无限挂起。对于非流式调用,
timeout=60是一个合理的起点。 - 在读取响应体之前调用
raise_for_status()。 失败的请求返回结构化错误对象,而不是补全结果——在 4xx 上检查json()会误导你。先让异常抛出,然后记录响应文本。
把请求体放在一个函数或小型配置对象中,这样流式和工具调用部分就能扩展它,而不是复制它。
为调用添加流式支持
先让非流式请求通过。然后再启用流式——失败模式不同,同时叠加两种改动会让错误变得难以区分。
开启流式
在现有请求体中添加一个字段:
{
"model": "gemini-4-carbon",
"stream": true,
"messages": [
{"role": "user", "content": "List three uses for a message queue."}
]
}
这就是协议的全部改动。服务器现在会返回一串事件,而不是一个 JSON 文档。
正确地消费流
关键规则:不要在流式响应上调用 .json()。 你会遇到解析错误,因为响应体不是一个单独的 JSON 对象。使用 requests 时,逐行迭代并分别解析每个分块:
import json, os, requests
response = requests.post(
f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gemini-4-carbon",
"stream": True,
"messages": [{"role": "user", "content": "List three uses for a message queue."}],
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
decoded = decoded[len("data: "):]
if decoded.strip() == "[DONE]":
break
try:
chunk = json.loads(decoded)
except json.JSONDecodeError:
continue
print(chunk)
需要注意什么
- 向
requests传入stream=True。 否则客户端会先缓冲整个响应体,之后你才看到一行内容,这就违背了初衷。 - 跳过空行和非 JSON 的保活消息。 上面的
try/except是刻意为之——流中可能包含不可解析为分块的行。 - 跨分块累积文本。 每个分块携带的是片段,不是完整回复。在文本增量到达时追加它们。
流式可用之后,在你的非流式测试中把 stream 改回 false,这样工具调用保持易于阅读。要了解 Carbon 目标的概览,gemini-4-carbon 模型页面 是一个不错的参考点。
为请求体添加工具调用
工具调用在两处改变请求:你声明工具,并且你要处理一个可能包含工具调用请求而非文本的响应轮次。只有在非流式文本调用通过之后才添加此功能。
声明工具
在 model 和 messages 旁边添加一个 tools 数组。每个工具有一个名称、一个描述,以及其参数的 JSON Schema。描述很重要——它是模型用来判断是否调用该工具的依据。
{
"model": "gemini-4-carbon",
"messages": [
{"role": "user", "content": "What is the weather in Lisbon?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}
]
}
工具调用循环
使用工具的请求是一段对话,而不是单次调用:
- 发送用户消息以及工具声明。
- 检查助手轮次。如果它包含工具调用参数,说明模型想让你运行某些东西。
- 执行本地函数——HiAPI 不会运行你的代码。
- 追加两条消息:助手的工具调用轮次,以及一条带有函数结果、与匹配调用 ID 关联的
tool角色消息。 - 重新发送完整消息历史。模型现在产出最终答案。
工具特有的失败点
- Schema 不匹配。 如果你的
parametersschema 将某个字段标记为必需,但结果中省略了它,后续轮次可能会被拒绝。保持 schema 精确。 - 丢弃历史。 每次重新发送都必须包含原始用户消息和工具调用轮次——而不仅仅是工具结果。
- 流式加工具。 工具调用参数可能被拆分到多个流分块中到达。在你学习流程期间,用
stream: false运行工具,这样每个轮次都以一个可读对象到达。
无需重写客户端即可切换模型和提供方
因为模型变体只是请求体中的一个字符串,切换目标属于配置变更,而不是重构。将客户端设计成从变量读取模型 ID——环境变量、配置文件、CLI 标志——绝不要在多个地方硬编码。
切换本身
export HIAPI_MODEL="gemini-4-carbon" # default
export HIAPI_MODEL="gemini-4-argon" # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex" # Vertex-backed Carbon
在代码中,在请求体里引用该变量:
payload = {
"model": os.environ["HIAPI_MODEL"],
"messages": messages,
}
@vertex 后缀随模型字符串一起传递。不要把它拆成单独字段或去掉——它是可路由 ID 的一部分,去掉它会静默地把你路由到非 Vertex 目标。
切换后需要重新测试什么
- 纯文本轮次 —— 确认 ID 被识别且鉴权仍然有效。
- 你最长的真实提示词 —— 不同变体处理长输入或结构化输入的方式可能不同;验证截断和格式。
- 流式 —— 重新运行流式路径,因为分块节奏和边界可能因目标而异。
- 工具调用 —— 重新验证完整的工具调用循环;参数格式是变体差异最常暴露的地方。
保留一个小型冒烟测试脚本,针对当前设置的 HIAPI_MODEL 运行这四项检查。这样切换提供方就变成了配置变更加一条命令,而不是一次调试会话。
排查常见的请求失败
几乎每个集成失败都可归入少数几类。匹配症状、应用修复,并在改动其他任何东西之前重新运行非流式基线。
鉴权与路由
- 401 或 403。 密钥缺失、过期或前缀不正确。检查请求头是否恰好是
Authorization: Bearer <key>,中间只有一个空格,并确认该变量确实已在运行代码的 shell 或进程中导出。打印前几个字符以确认。 - 端点返回 404。 你的基础 URL 错误或路径段重复。模型放在请求体里,而不是 URL 里。
- 模型未找到。 模型 ID 有拼写错误。逐字符对照
gemini-4-argon、gemini-4-carbon和gemini-4-carbon@vertex——@vertex后缀是人们最常漏掉的。
请求体问题
- 400 并带有 schema 消息。 通常是
messages格式错误:缺少role、content本应是字符串却不是,或数组为空。从本指南中最小的两行请求体开始,一次添加一个字段。 - 添加工具后返回 400。 你的
parametersschema 是无效的 JSON Schema,或者工具结果轮次与助手消息中的调用 ID 不匹配。记录完整响应体——错误文本会指出有问题的字段。
流式失败
- 响应上的 JSON 解析错误。 你在对流调用
.json()。改为逐行迭代并解析每个分块,并跳过空行和[DONE]标记。 - 响应一次性到达。 你忘了在客户端调用中设置
stream=True,所以requests缓冲了整个响应体。 - 输出被截断。 你的循环提前中断——通常是在空行或保活消息上。只在显式的流结束标记处停止。
调试纪律
按照你构建时的相同顺序进行二分排查:鉴权和请求头,然后非流式文本,然后流式,然后工具。每一层都有不同的失败特征,所以你最后改的东西几乎总是原因。每次失败时记录 HTTP 状态和完整响应体——消息通常会指出具体字段。
先让基线在 gemini-4-argon 或 gemini-4-carbon 上通过,然后从那里扩展请求体。如果你仍在决定哪个变体适合你的工作负载,gemini-4-argon 模型页面 是入手之处。