这篇教程带你从零做一套自己的模型选型工具:先在本地跑通 Gemini 4 Neon 的对话与工具调用,再把日常任务拆成"简单问答 / 长文摘要 / 编码任务"三档,用一个计量脚本同时记录 token 用量和耗时,最后得到一张属于你自己的对照表,据此决定什么时候该用 Neon、什么时候省下来切回 Hydrogen。
这套方法不依赖某个特定模型——模型 ID、单价都以官方文档当前版本为准,脚本里留了配置位,你换成自己账号能用的模型名即可。
前置条件清单
动手前确认这几项:
1. 一个可用的 API Key。在 Google AI Studio 里创建,创建后立刻复制保存,页面关掉通常就看不到了。
2. Python 3.10 或以上。低版本在类型标注上会踩坑。
3. 安装官方 SDK。命令行执行:
```bash
python -m venv .venv
source .venv/bin/activate # Windows 用 .venv\Scripts\activate
pip install --upgrade google-genai
```
4. 把 Key 放进环境变量,不要写死在代码里:
```bash
export GEMINI_API_KEY="你的key" # Windows: set GEMINI_API_KEY=...
```
5. 确认你要用的模型 ID。本文用 Neon 指代你接入的主力模型、Hydrogen 指代更轻更快的那一档,具体字符串去官方模型列表页复制,别凭记忆拼。
第一步:跑通最小对话
新建 hello.py:
```python
import os
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
MODEL_ID = "在此填入官方模型列表中的 Neon 模型 ID"
resp = client.models.generate_content(
model=MODEL_ID,
contents="用三句话解释什么是AI 词典:向量数据库">向量数据库,面向非技术读者。",
)
print(resp.text)
```
运行 python hello.py,能看到一段中文回答就说明链路通了。这一步失败的话,九成是 Key 没生效或者模型 ID 拼错,先解决这两点再往下走。
第二步:把 token 与耗时记录下来
选型决策不能靠感觉,得有数。写一个计量函数,每次调用都返回"输入 token / 输出 token / 总耗时 / 输出文本"。
```python
import time
from google import genai
from google.genai import types
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
def call(model: str, prompt: str, max_out: int = 2048, temperature: float = 0.2):
cfg = types.GenerateContentConfig(
temperature=temperature,
max_output_tokens=max_out,
)
t0 = time.perf_counter()
resp = client.models.generate_content(model=model, contents=prompt, config=cfg)
elapsed = time.perf_counter() - t0
u = resp.usage_metadata
in_tok = getattr(u, "prompt_token_count", 0) or 0
out_tok = getattr(u, "candidates_token_count", 0) or 0
return {
"model": model,
"in_tok": in_tok,
"out_tok": out_tok,
"seconds": round(elapsed, 2),
"text": resp.text or "",
}
```
几个注意点:
usage_metadata在某些情况下可能为空,所以加了getattr兜底。candidates_token_count是可见输出;部分模型的推理过程也会计入输出计费,具体口径看官方计费文档。resp.text在触发内容安全拦截时可能为空,不要直接.strip(),会抛异常。
第三步:加上工具调用
真实业务里光会聊天不够,得让模型能查数据。下面是一个可跑通的单轮工具调用循环,示例工具是"查城市天气"。
```python
from google.genai import types
def get_weather(city: str) -> str:
换成你自己的数据源
fake = {"北京": "晴,18℃", "上海": "多云,22℃"}
return fake.get(city, "暂无数据")
weather_decl = types.FunctionDeclaration(
name="get_weather",
description="查询指定城市的当前天气",
parameters=types.Schema(
type=types.Type.OBJECT,
properties={
"city": types.Schema(type=types.Type.STRING, description="城市中文名"),
},
required=["city"],
),
)
def chat_with_tools(user_text: str):
config = types.GenerateContentConfig(
tools=[types.Tool(function_declarations=[weather_decl])],
temperature=0.1,
)
contents = [types.Content(role="user", parts=[types.Part(text=user_text)])]
while True:
resp = client.models.generate_content(
model=MODEL_ID, contents=contents, config=config
)
cand = resp.candidates[0]
parts = cand.content.parts or []
calls = [p.function_call for p in parts if getattr(p, "function_call", None)]
if not calls:
return resp.text
把模型的调用意图回写进对话历史
contents.append(cand.content)
result_parts = []
for fc in calls:
result = get_weather(**dict(fc.args))
result_parts.append(
types.Part.from_function_response(
name=fc.name, response={"result": result}
)
)
contents.append(types.Content(role="user", parts=result_parts))
```
关键在循环结构:模型返回 function_call → 你执行本地函数 → 用 from_function_response 把结果塞回 contents → 再请求一次。少了"回写历史"这一步,模型会因为看不到工具结果而死循环。
工具声明里的 description 值得认真写,它直接决定模型选不选这个工具、参数填得对不对。
第四步:构造三档测试任务
为了让结果可比,每个档位都要固定输入规模、固定输出上限、跑多次取中位数。
档位 A:简单问答。 prompt 控制在几十个字,比如"把这句话改得更正式:'这个方案我觉得还行'"。这类请求的输出短、输入短,是日常调用量最大的一类。
档位 B:长文摘要。 输入要够长才有代表性。用一段几千字的材料,复制拼接扩到目标长度:
```python
base = open("sample.md", encoding="utf-8").read()
long_doc = (base * 6)[:30000] # 约三万字,按字符截断
prompt_b = f"请用 300 字以内概括下面材料的核心结论,并列出三条行动项:\n\n{long_doc}"
```
档位 C:编码任务。 给一段有 bug 的函数,要求定位并给出修正版:
```python
prompt_c = """下面这个函数用于统计词频,但在处理空输入和大小写时有问题。
请指出问题并给出修正后的完整代码,不要解释太多。
def word_count(text):
result = {}
for w in text.split(" "):
result[w] = result.get(w, 0) + 1
return result
"""
```
跑的时候先各做一次 warmup 丢弃结果(首次请求有连接建立和冷启动开销),然后每个档位跑 3 到 5 次。
```python
import statistics
def benchmark(model, prompt, n=3, max_out=1024):
call(model, prompt, max_out) # warmup
rows = [call(model, prompt, max_out) for _ in range(n)]
return {
"in_tok": statistics.median(r["in_tok"] for r in rows),
"out_tok": statistics.median(r["out_tok"] for r in rows),
"sec": statistics.median(r["seconds"] for r in rows),
}
```
第五步:把 token 换算成钱
单价会变,所以不要写死在代码里到处引用。集中放一个字典,数值去官方定价页抄当前值:
```python
单位:每百万 token 的美元价格,以官方定价页当前数值为准
PRICE = {
"NEON": {"in": None, "out": None},
"HYDROGEN": {"in": None, "out": None},
}
def cost_usd(tier, in_tok, out_tok):
p = PRICE[tier]
return in_tok / 1_000_000 * p["in"] + out_tok / 1_000_000 * p["out"]
```
填好之后跑一遍,把结果整理成表。外形大致是这样(数字是你自己测出来的,不是别人的):
| 档位 | 模型 | 输入 token | 输出 token | 耗时(秒) | 单次成本 |
|---|---|---|---|---|---|
| A 简单问答 | Hydrogen | 低 | 低 | 快 | 极低 |
| A 简单问答 | Neon | 低 | 低 | 略慢 | 略高 |
| B 长文摘要 | Hydrogen | 高 | 中 | 中 | 中 |
| B 长文摘要 | Neon | 高 | 中 | 较慢 | 较高 |
| C 编码任务 | Hydrogen | 中 | 高 | 中 | 中 |
| C 编码任务 | Neon | 中 | 高 | 较慢 | 较高 |
真正的决策依据是"质量差多少"。所以每个档位都要人工看一遍输出,给个粗糙的可用/不可用判断——A 档如果两档都对,就直接选快的那档;C 档如果 Hydrogen 给的代码跑不通、Neon 一次过,那多花的钱就值。
第六步:得出你自己的切换规则
测完之后,把结论写成几条硬规则,嵌进代码里,而不是每次靠感觉:
```python
def pick_model(task_type: str, input_chars: int, need_code_quality: bool):
if task_type == "qa" and input_chars < 2000:
return HYDROGEN_ID
if task_type == "summary" and input_chars < 50000:
return HYDROGEN_ID
if task_type == "coding" and need_code_quality:
return NEON_ID
return NEON_ID
```
下面这几条经验,多数团队实测下来都成立,可以当作初始设定:
- 简单问答一律先用 Hydrogen。这类任务两档模型差距通常看不出来,而调用量最大,省下来的都是纯利润。
- 长文摘要的关键变量是输入长度,不是模型档位。同样的三万字文档,两档模型的输入 token 完全一样,成本差距主要来自单价和输出长度。如果 Hydrogen 摘得住要点,就没必要上 Neon。
- 编码任务优先给 Neon。代码正确率差一点,返工的人力成本远高于 token 差价。
- 切回 Hydrogen 的触发条件要写死:连续若干次输出被判为"可用"、任务类型属于低风险、输入规模在阈值以内——三个条件同时满足就降档。
- 不要靠重试省钱。用 Hydrogen 跑三次才对,不如直接用 Neon 跑一次。
还有一个常被忽略的省钱手段:如果同一份长文档要被反复提问,看官方是否提供上下文缓存能力,命中缓存的部分通常比重新输入划算得多,具体规则和折扣以官方文档为准。
常见坑与排错
报 429 / RESOURCE_EXHAUSTED。 触发了速率或配额限制。做法是指数退避重试,别用固定间隔硬刷:
```python
import time, random
def call_with_retry(fn, retries=4):
for i in range(retries):
try:
return fn()
except Exception as e:
if "429" in str(e) and i < retries - 1:
time.sleep((2 ** i) + random.random())
continue
raise
```
回答被截断。 检查 max_output_tokens,默认值可能比你以为的小。做长文摘要时尤其容易踩。
resp.text 返回 None。 多半是安全策略拦截或候选为空。打印 resp.candidates[0].finish_reason 就能看到原因,别在代码里假设它一定有值。
测出来的延迟波动很大。 网络链路影响常常大于模型本身。要用中位数而不是单次值;如果关心首字体验,改用流式接口单独测"首 token 时间",它和总时长是两个指标。
工具调用死循环。 一定是忘了把 candidates[0].content 追加进 contents,模型看不到自己发起过调用,就会一直重试。
长文档传进去报参数过长。 先确认模型支持的上下文窗口,再确认你的文本是不是被重复拼接放大了。用 len(prompt) 打印实际字符数,别猜。
成本算出来对不上账单。 你漏算了推理 token 或者缓存命中部分。以官方计费文档的口径为准,脚本里记录的是接口返回的用量,两者允许有差异。
下一步建议
跑通这套之后,可以做三件事把结论变成生产力:
1. 把 pick_model 抽成独立模块,所有业务代码只调它,不直接写模型 ID。以后换模型只改一处。
2. 把测试集扩到 20 到 30 条真实样本。三条样例只能验证链路,验证不了质量差距。从线上日志里挑真实请求做回归,结论才靠得住。
3. 加一层结果校验再降档。比如编码任务用单元测试自动判定通过与否,摘要任务用关键词覆盖度判定。有了自动判定,"什么时候切回 Hydrogen"就从人工判断变成规则判断,降档才敢放开。
最后提醒一句:模型的价格、上下文长度、限流额度都在持续变化,本文所有数值位置都留了配置入口,定期去官方页面核对一遍再更新,比记住任何结论都管用。
