
Gemini 4 Carbon API 是 Google 为最难的编码工作推荐的模型。Google 为多步骤调试和长周期智能体编码打造了它,并表示它比 Argon 花更多 token 去探索、推理和运行验证循环。本指南通过 PoYo 兼容 OpenAI 的接口,把 gemini-4-carbon(模型页)接入一个编码智能体。这个智能体会流式输出、能读取代码仓库的一大部分、在达到硬性的轮数和金额预算时停止,并知道何时把工作交给 Argon。
如果你还没有发出第一个请求,请先阅读 Gemini 4 Carbon API 指南。
这个 API 能为编码智能体提供什么
| 项目 | PoYo 上的 Gemini 4 Carbon |
|---|---|
| 模型 ID | gemini-4-carbon |
| 本文智能体使用的接口 | POST https://api.poyo.ai/v1/chat/completions(OpenAI SDK,base_url="https://api.poyo.ai/v1") |
| 原生替代方案 | POST /v1beta/models/gemini-4-carbon:generateContent 和 :streamGenerateContent |
| 上下文窗口 | 1M token:文本、图像、音频、视频、PDF |
| 每次响应最大输出 | 64K token |
| 流式输出 | "stream": true;最后一个 chunk 带有 finish_reason 和 usage |
| 价格 | 每 1M token 输入 $1.60 / 输出 $8.00 / 缓存读取 $0.08(320 / 1,600 / 16 积分) |
| 速率限制 | PoYo 文档说明 LLM 接口目前没有速率限制 |
| 错误 | 400 字段无效,401 密钥错误,402 积分不足,404 模型未知;429 / 500 / 502 / 503 用退避策略重试 |
Chat Completions 文档说明了以下请求字段:model、messages(字符串 content,角色为 system、user 或 assistant)、max_tokens、stream、temperature、top_p、stop、n 以及惩罚字段。下面的智能体只使用这些字段。
工具调用:目前文档中有什么
PoYo 为 Anthropic Messages 和 Responses 说明了 tools。对于 Gemini 模型,无论是 Chat Completions 还是 Gemini Native,都没有说明 tools 或函数声明。gemini-4-carbon 不支持 Responses。
因此这个智能体不发送 tools 数组,而是在普通消息内容中使用 JSON 动作协议。系统提示列出允许的动作,模型每轮回复一个 JSON 对象,你的代码执行该动作,并把结果作为下一条用户消息发回。这种方式适用于任何聊天模型。等 PoYo 为 Gemini 说明原生函数调用后,你可以把解析器换成真正的工具调用,循环的其余部分保持不变。
这样做还有安全上的好处:模型只能请求你自己编写的四个动作,无法运行任意 shell 命令。
长上下文仓库输入:1M 输入,64K 输出
1M token 的窗口让你可以在第一轮就发送代码仓库的大部分内容,而不必一次取一个文件。Google 的发布表格给出了这样做的理由:Carbon 在 256K–1M token 的 GraphWalks 上得分 96.2%,Argon 为 84.2%。有三个限制决定了循环的设计:
- 每一轮都会重新发送全部历史。 快照在每次调用时都会再次计费。一个 300K token 的快照跑 12 轮,至少是 3.6M 输入 token,按每 1M $1.60 计算,在任何输出之前就是 $5.76。
- 每次响应的输出上限为 64K。 每个
write_file动作只要求写一个文件,不要在一次回复中重写整个仓库。 - token 计数要测量,不要猜。 PoYo 没有说明分词器接口。读取第一次调用的
usage.prompt_tokens,再把MAX_SNAPSHOT_CHARS调到你想要的 token 预算。
缓存。 PoYo 价目表中有 Carbon 的缓存读取价格(每 1M $0.08,新输入为 $1.60),Google 对缓存输入打 95% 折扣。PoYo 文档没有为 Gemini 模型说明缓存请求参数或缓存 token 用量字段。这个循环不发送任何缓存参数,并把每个提示 token 都按完整输入价格计入预算。让系统提示和快照保持为不变的前缀不需要任何成本,账单会显示是否有读取按缓存价格计费。
Python 中的有界智能体循环
import json
import os
import subprocess
import time
from pathlib import Path
from openai import OpenAI, APIStatusError
client = OpenAI(api_key=os.environ["POYO_API_KEY"], base_url="https://api.poyo.ai/v1")
CARBON, ARGON = "gemini-4-carbon", "gemini-4-argon"
PRICE_IN, PRICE_OUT = 1.60, 8.00 # PoYo USD per 1M tokens, same for both (2026-11-16)
MAX_TURNS = 12
BUDGET_USD = 2.00
MAX_TOKENS_PER_TURN = 16_000 # Carbon allows up to 64,000
MAX_SNAPSHOT_CHARS = 400_000 # tune against usage.prompt_tokens
MAX_RESULT_CHARS = 20_000
REPO = Path("./my-repo").resolve()
SYSTEM = """You are a coding agent working in a Python repository.
Reply with exactly one JSON object and nothing else. Allowed actions:
{"action": "read_file", "path": "<relative path>"}
{"action": "write_file", "path": "<relative path>", "content": "<full file content>"}
{"action": "run_tests"}
{"action": "done", "summary": "<what changed and why>"}"""
def snapshot() -> str:
parts, total = [], 0
for p in sorted(REPO.rglob("*.py")):
block = f"### {p.relative_to(REPO)}\n{p.read_text(encoding='utf-8', errors='replace')}\n"
if total + len(block) > MAX_SNAPSHOT_CHARS:
break
parts.append(block)
total += len(block)
return "".join(parts)
def safe_path(rel: str) -> Path:
p = (REPO / rel).resolve()
if not p.is_relative_to(REPO):
raise ValueError("path outside repository")
return p
def execute(action: dict) -> str:
kind = action.get("action")
if kind == "read_file":
return safe_path(action["path"]).read_text(encoding="utf-8", errors="replace")
if kind == "write_file":
safe_path(action["path"]).write_text(action["content"], encoding="utf-8")
return "written"
if kind == "run_tests":
r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
return f"exit={r.returncode}\n{r.stdout}\n{r.stderr}"
raise ValueError(f"unknown action {kind!r}")
def call(model: str, messages: list):
"""One streamed turn. Returns (text, usage, finish_reason)."""
for attempt in range(4):
try:
stream = client.chat.completions.create(
model=model, messages=messages, max_tokens=MAX_TOKENS_PER_TURN, stream=True
)
text, usage, finish = [], None, None
for chunk in stream:
if chunk.choices:
choice = chunk.choices[0]
if choice.delta and choice.delta.content:
text.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
finish = choice.finish_reason or finish
if getattr(chunk, "usage", None):
usage = chunk.usage
return "".join(text), usage, finish
except APIStatusError as e:
if e.status_code in (429, 500, 502, 503) and attempt < 3:
time.sleep(2 ** attempt)
continue
raise # 400, 401, 402, 404: fix the request or the account, don't retry
def parse(text: str) -> dict:
t = text.strip()
if t.startswith("```"):
t = t.strip("`").removeprefix("json").strip()
return json.loads(t)
def run_agent(task: str, model: str = CARBON) -> dict:
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Repository snapshot:\n{snapshot()}\n\nTask: {task}"},
]
spent, last_prompt = 0.0, 0
for turn in range(1, MAX_TURNS + 1):
# Worst case for the next turn: at least last turn's input plus a full output
worst_next = last_prompt / 1e6 * PRICE_IN + MAX_TOKENS_PER_TURN / 1e6 * PRICE_OUT
if spent + worst_next > BUDGET_USD:
return {"status": "budget_stop", "turns": turn - 1, "spent_usd": round(spent, 4)}
text, usage, finish = call(model, messages)
if usage is None:
raise RuntimeError("no usage in stream; stopping so the budget stays enforceable")
spent += usage.prompt_tokens / 1e6 * PRICE_IN + usage.completion_tokens / 1e6 * PRICE_OUT
last_prompt = usage.prompt_tokens
messages.append({"role": "assistant", "content": text})
if finish == "length":
messages.append({"role": "user", "content": "Reply was cut off. Send one shorter JSON action."})
continue
try:
action = parse(text)
except json.JSONDecodeError:
messages.append({"role": "user", "content": "Reply with exactly one JSON object."})
continue
if action.get("action") == "done":
return {"status": "done", "summary": action.get("summary"), "turns": turn, "spent_usd": round(spent, 4)}
try:
result = execute(action)
except Exception as e: # report the failure to the model instead of crashing
result = f"error: {e}"
messages.append({"role": "user", "content": f"Result of {action.get('action')}:\n{result[:MAX_RESULT_CHARS]}"})
return {"status": "max_turns", "turns": MAX_TURNS, "spent_usd": round(spent, 4)}
if __name__ == "__main__":
print(run_agent("tests/test_parser.py::test_unicode fails. Find the root cause and fix it."))
Path.is_relative_to 需要 Python 3.9 或更高版本。由于 write_file 会覆盖文件,请在代码仓库的副本或分支上运行智能体。
成本保护如何工作
| 保护措施 | 防止什么 | 数字从哪里来 |
|---|---|---|
MAX_TURNS | 永远不调用 done 的循环 | 由你决定;12 是一个起点 |
BUDGET_USD + 最坏情况检查 | 下一次调用花费超出上限 | 流最后一个 chunk 中的 usage.prompt_tokens 和 usage.completion_tokens,按 PoYo 的 $1.60 / $8.00 计算 |
MAX_TOKENS_PER_TURN | 单次失控的回复 | max_tokens,Carbon 最多 64,000 |
MAX_RESULT_CHARS | 巨大的测试日志让之后每一轮都膨胀 | 结果进入历史前先截断 |
usage is None → 停止 | 无法衡量的静默花费 | PoYo 文档说明最后一个流 chunk 中带有 usage |
不重试 402 | 余额为零时的重试风暴 | PoYo 错误码 |
Google 对 Carbon 的输出计价包含思考 token,所以一轮计费的输出可能多于可见的 JSON。这就是预算使用 completion_tokens、从不按收到的字符数计算的原因。估算把所有输入都按未缓存计算,因此是 PoYo 实际计费的上限。前几次运行时请用控制台核对。
最坏情况检查是保守的。历史为 300K token 时,再跑一轮至少需要 $0.48 的输入,在 max_tokens 为 16K 时最多再加 $0.128 的输出。在 $2.00 的预算下,循环会在可能越过上限的那次调用之前停止。
何时回退到 Gemini 4 Argon
Argon 接受相同的请求,每个输入和输出 token 的价格也相同。Google 称它是“大多数软件工程和知识工作的理想选择”,响应更快,每轮 token 花费更低。在以下情况下,用 run_agent(task, model=ARGON) 把任务路由给它:
- 任务是常规的。 小修复、单文件修改和编写测试不需要 Carbon 额外的验证 token。
- 单次响应必须超过 64K token。 Carbon 的输出上限为 64K。我们的 Argon 指南介绍了 Argon 大得多的输出上限。
- 你想要一次便宜的首次尝试。 先跑 Argon,只有测试仍然失败时才升级到 Carbon。Gemini 4 Carbon API vs Gemini 4 Argon API 中的路由器就是这样做的。
把 Carbon 留给全仓库范围的根因定位和大量依赖终端的循环。在 Google 的表格中,Carbon 在 Terminal-Bench 4.0 (AA) 上得分 65.2%,Argon 为 57.1%;在 SWE-sweep 上为 9.6% 对 4.3%。Google 的开放公告还建议一种分工:Carbon 承担架构、协调和审计角色,搭配更快、更轻量的模型做并行工作。在这个循环里,就是跑一次 Carbon 规划器,把文件分配给 Argon 工作者。
两个模型的预算见 Gemini 4 Carbon API 价格文章。如果你在为智能体评估其他厂商,请参阅 Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API。
常见问题
Gemini 4 Carbon API 在 PoYo 上支持函数调用吗?
PoYo 当前文档没有为 Gemini 模型在 Chat Completions 或 Gemini Native 中说明 tools 或函数声明。工具在 Anthropic Messages 和 Responses 中有说明。本指南在消息内容中使用 JSON 动作协议,只需要文档中说明的字段。
可以用 OpenAI Python SDK 调用 Gemini 4 Carbon API 吗?
可以。创建 OpenAI(api_key=..., base_url="https://api.poyo.ai/v1"),并向 chat.completions.create 传入 model="gemini-4-carbon"。设置 stream=True 即可流式输出,最后一个 chunk 带有 usage。
Gemini 4 Carbon API 的最大输出和上下文窗口是多少?
上下文 1M token,每次响应最多 64K 输出 token。把 max_tokens 设为 64,000 或更小。
如何在智能体循环中限制 Gemini 4 Carbon API 的费用?
限制轮数、限制每轮 max_tokens、截断工具结果,并在已花费金额加上最坏情况下一轮的费用会超出预算时停止。在 PoYo 上,按每 1M token usage.prompt_tokens × $1.60 和 usage.completion_tokens × $8.00 计算花费。
Gemini 4 Carbon API 支持上下文缓存吗?
PoYo 列出的 Carbon 缓存读取价格为每 1M token $0.08(16 积分)。其文档目前没有为 Gemini 模型说明缓存请求参数或缓存 token 用量字段,所以请按完整输入价格为提示做预算,并在账单中查看是否有按缓存价格计费的项目。
编码智能体什么时候应该用 Gemini 4 Argon 而不是 Carbon?
常规编码、任何必须超过 64K token 的单次响应,以及在升级到 Carbon 之前做一次更便宜的首次尝试时,使用 Argon。两者在 PoYo 上都是每 1M token $1.60 / $8.00,但 Google 表示 Argon 每轮使用的 token 更少。