跳到主内容
快讯直播
AI智模界
教程

上手 Gemini 4 Neon:API 接入、任务分层与性价比实测

这篇教程带你从零做一套自己的模型选型工具:先在本地跑通 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"就从人工判断变成规则判断,降档才敢放开。

最后提醒一句:模型的价格、上下文长度、限流额度都在持续变化,本文所有数值位置都留了配置入口,定期去官方页面核对一遍再更新,比记住任何结论都管用。

AI 生成本文由 AI 基于公开信息自动生成,仅供参考。