Gemini 指南
双子星漫游指南:关于本站的 Gemini 调用细节,在此汇总。
Gemini 调用方式
对于 Gemini 系列,我们提供原生调用和 Openai 兼容这 2 种调用方式。
使用前运行 pip install google-genai
或 pip install -U google-genai
,安装(更新)原生依赖。
1️⃣ 对于原生调用,主要是在内部传入 AiHubMix 密钥和请求链接。需要注意的是,这个链接和常规的 base_url
写法不同,请参考示例:
2️⃣ 对于 Openai 兼容格式,则维持通用的 v1
端点:
3️⃣ 对于 2.5 系列,如果你需要显示推理过程,可以使用以下 2 种方式:
- 原生调用:传入
include_thoughts=True
- OpenAI 兼容方式:传入
reasoning_effort
相关的详细调用可以参考下文的代码示例。
Gemini 2.5 系列的「推理」说明
- 2.5 系列都是推理模型。
- 2.5 flash 是混合模型,类似 claude sonnet 3.7,可以通过用
thinking_budget
控制推理预算来达到最佳效果。 - 2.5 pro 是纯粹的推理模型,因此不能关闭 thinking、也不显式传递推理预算。
Python 调用参考如下:
Gemini 2.5 Flash 支持
Openai 兼容方式调用参考如下:
- 用于复杂任务时,只需要将模型 id 设置为默认开启思考的
gemini-2.5-flash-preview-04-17
即可。 - Gemini 2.5 Flash 通过
budget
(思考预算)来控制思考的深度,范围 0-16K,目前转发采用的是默认预算 1024,最佳边际效果为 16K。
多媒体文件
Aihubmix 目前只支持小于 20MB 的多媒体文件(图片、音频、视频),用 inline_data
上传。
大于 20M 的多媒体需要用 File API(尚未支持),待完善状态跟踪,返回 upload_url
。
Code Execution
自动代码解析器用例参考:
上下文缓存
Gemini 在原生 API 下默认启用了隐式上下文缓存,无需开发者手动操作。每一次 generate_content
请求,系统会自动为输入内容建立缓存。当后续请求与此前内容完全一致时,将直接命中缓存,返回上一次的推理结果,大幅提升响应速度并有机会节省 token 消耗。
- 缓存自动生效,无需手动配置。
- 缓存仅在内容、模型、参数完全一致时生效;任何字段不同都会视为新请求,不命中缓存。
- 缓存有效期(TTL)由开发者设定,也可以不设置。如果未指定,默认为 1 小时。无最小或最大时长限制,费用取决于缓存 token 数与缓存时间。
- 虽然 Google 官方对 TTL 不设上下限,但由于我们作为转发平台,仅支持有限的 TTL 配置范围,不保证永久有效。
注意事项
-
无成本节省保证:缓存 token 的计费为输入原价的 25%,理论上输入部分可最多节省 75% 成本,但 Google 官方并未承诺必然节省,实际账单还需结合缓存命中率、token 类型与存储时长共同评估。
-
缓存命中条件:建议将重复的上下文放在请求前部,将易变内容(如用户输入)置于后部,以提高缓存命中率。
-
缓存命中反馈:如果响应结果命中缓存,在
response.usage_metadata
中会包含cache_tokens_details
字段,并有cached_content_token_count
,开发者可以据此判断本次请求是否命中缓存。
示例响应字段(命中缓存时):
代码示例:
命中缓存时,
response.usage_metadata
会包含如下结构:
**核心结论:**隐式缓存支持自动命中与命中反馈。开发者可以通过 usage_metadata 判断命中情况。成本节省非保证,实际效果因请求结构和使用场景而异。
Function calling
使用 openai 兼容方式调用 Gemini 的 function calling 功能时,需要在请求体内部传入tool_choice="auto"
,否则会报错。
输出结果示例:
Tokens 用量追踪
- Gemini 原生采用
usage_metadata
来追踪使用的 token,其中的字段对应如下:
- prompt_token_count: 输入 token 数
- candidates_token_count: 输出 token 数
- thoughts_token_count: 推理使用的 token 数,性质上也是输出 token
- total_token_count: 总 token 使用量(输入+输出)
- 对于 OpenAI 兼容格式,则采用
.usage
来追踪,字段对应如下:
- usage.completion_tokens: 输入 token 数
- usage.prompt_tokens: 输出 token 数(包含推理使用的 token 数)
- usage.total_tokens:总 token 使用量
使用方法如下: