Google Gemini 系列模型是 Google DeepMind 推出的原生多模态大语言模型，自 2023 年 12 月发布以来经历了多次迭代，是 OpenAI GPT 系列的最主要竞争对手之一。本文详细解析 Gemini API 的使用方式、参数行为、最佳实践以及与其他平台的差异。
| 时间 | 版本 | 关键特性 |
|---|---|---|
| 2023-12 | Gemini 1.0 | 首批多模态原生模型（Pro/Ultra） |
| 2024-02 | Gemini 1.5 | 上下文窗口扩展至 1M，MoE 架构改进 |
| 2024-05 | Gemini 1.5 Flash | 性价比优化版本，推理速度提升 2-3x |
| 2024-12 | Gemini 2.0 Flash | 支持实时多模态输入（音频/视频/图像流） |
| 2025-03 | Gemini 2.5 | 思维链增强，MLE-bench 超越 GPT-4o |
| 模型 | 上下文 | 架构特点 | 输入价格 / 1M tokens | 输出价格 / 1M tokens |
|---|---|---|---|---|
gemini-2.5-pro |
2M | 思维链推理增强，原生多模态 | $5.00 $20.00 | |
gemini-2.0-flash |
1M | 低延迟，实时流式多模态 | $0.35 $1.05 | |
gemini-1.5-pro |
1M | 稳定旗舰 | $3.50 $10.50 | |
gemini-1.5-flash |
1M | 快速轻量 | $0.35 $1.05 | |
gemini-1.0-pro |
32K | 标准版本（逐步退役） | $0.50 $1.50 |
注意：
gemini-1.0-ultra已在 2025 年初被gemini-2.0-pro替代。当前推荐首选gemini-2.0-flash进行日常推理，复杂任务使用gemini-2.5-pro。
Gemini 1.5/2.0 系列采用稀疏 MoE（Mixture of Experts）架构，这一点与 GPT-4 的架构设计有相似之处。核心思想：
MoE 的参数量与推理量对比（估算）：
| 模型 | 总参数量 | 每个 token 激活参数 | 推理计算量比率 |
|---|---|---|---|
| GPT-3.5 | 175B | 175B | 1x |
| Gemini 1.5 Pro | ~500B+ | ~60-80B | ~0.4x |
| Gemini 2.0 Flash | ~200B | ~20-30B | ~0.15x |
| GPT-4 | ~1.7T | ~280B | 1.6x |
实际收益：MoE 架构使得 Gemini 1.5 Flash 在推理速度上比 GPT-3.5 快约 2-3 倍，同时保持接近 GPT-4 的生成质量。
与 OpenAI GPT-4o 的"后期融合"不同，Gemini 从预训练阶段就开始对齐多模态数据：
输入流程示意图：
文本 ──────┐
图片 ──────┤
音频 ──────┼─→ 统一 Tokenizer ─→ MoE Transformer ─→ 文本/Token 输出
视频 ──────┤
代码 ──────┘
关键区别：
实际效果差异（基于公开 Benchmarks）：
| 基准测试 | GPT-4o (2024-05) | Gemini 1.5 Pro | Gemini 2.0 Flash |
|---|---|---|---|
| MMLU (知识推理) | 88.7% | 85.9% | 88.4% |
| MMMU (多模态) | 69.1% | 68.9% | 73.1% |
| MathVista (数学推理) | 63.0% | 63.7% | 69.3% |
| Video-MME (视频理解) | 71.5% | 73.2% | 78.4% |
在多模态和视频理解任务上，Gemini 系列具有明显优势。
| 属性 | 值 |
|---|---|
| 官网 | https://ai.google.dev |
| API 文档 | https://ai.google.dev/gemini-api/docs |
| API 版本 | v1alpha（试验）/ v1beta（推荐）/ v1（稳定） |
| 基础 URL | https://generativelanguage.googleapis.com/{version}/models/{model-id} |
| OAuth URL | https://oauth2.googleapis.com/token |
| 认证方式 | API Key（URL 参数 ?key=xxx）或 OAuth 2.0 |
| 方式 | 适用场景 | 安全性 | 用法 |
|---|---|---|---|
| API Key | 开发测试、个人项目 | ⭐⭐ | ?key=YOUR_API_KEY |
| OAuth 2.0 | 生产环境、用户数据 | ⭐⭐⭐⭐ | Authorization: Bearer TOKEN |
获取 API Key：访问 Google AI Studio → Settings → Get API Key。免费层提供每日 60 次请求的额度。
# 标准生成端点
GET/POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent
# 流式生成端点
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent
# 多轮对话（包含历史上下文）
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent
# 需要在 contents 中传入完整历史
| 参数 | 类型 | 范围 | 默认值 | 作用 |
|---|---|---|---|---|
temperature |
float | 0-2 | 1.0 | 控制输出随机性 |
maxOutputTokens |
int | 1-8192 | 2048 | 最大输出 token 数 |
topP |
float | 0-1 | 0.95 | Nucleus sampling 累积概率阈值 |
topK |
int | 1-∞ | 40 | 每步只考虑概率最高 K 个 token |
stopSequences |
string[] | - | [] | 停止序列（最多 5 个） |
presencePenalty |
float | -2.0 - 2.0 | 0 | 话题重复惩罚 |
frequencyPenalty |
float | -2.0 - 2.0 | 0 | 词汇频率惩罚 |
candidateCount |
int | 1-8 | 1 | 返回候选数（需付费层） |
seed |
int | - | None | 随机种子（部分控制可复现性） |
以下是用同一 prompt"写一句关于 AI 的短诗"在不同 temperature 下的输出示例：
| temperature | 输出示例 | 特点 |
|---|---|---|
| 0.1 | "人工智能如同一面镜子，映照出人类智慧的无穷可能。" | 重复性高，保守安全 |
| 0.5 | "AI 是数据的梦境，在硅基的神经网络中编织逻辑的星辰。" | 有创意但不偏离主题 |
| 1.0 | "硅基的神经元，在数据的海洋中摸索，向着智慧的逻辑黎明航行。" | 创意丰富 |
| 1.5 | "电子的迷雾中，无名的洪流正在结晶成自我认知的第一个核——" | 可能偏离主题 |
| 2.0 | "深渊的字节自我注视着由代码编织的每一个光谱维度领域之外……" | 经常产生无意义输出 |
建议取值范围：
temperature=0.1-0.3temperature=0.5-0.7temperature=0.8-1.2temperature=1.0-1.5Gemini 特有的 topK 参数配合 topP 形成两层采样过滤机制：
第一步：topK 过滤
所有候选 token（词汇表 V）
↓
选择概率最高的 K 个 token（例如 K=40）
↓
第二步：topP 过滤
在 K 个 token 中，按概率从高到低累加
直到累积概率超过 P（例如 0.9）
↓
最终候选集合
从剩余 token 中按概率采样
不同 topK 的效果对比（词汇表大小 ~32K，temperature=1.0，topP=0.95）：
| topK | 每一步候选数 | 特点 | 适用场景 |
|---|---|---|---|
| 1 | 1 | 贪心解码（等同于 greedy） | 需要精确答案时 |
| 5 | 5-5 | 高度受限，多样性低 | 代码生成 |
| 40 | 15-40 | 默认值，平衡性 | 通用 |
| 200 | 50-200 | 多样性较高 | 创意写作 |
| 1000 | 100-600 | 接近不做 topK 过滤 | 最大多样性 |
实用建议：
topK=10~20，temperature=0.7topK=100~200，topP=0.95| Gemini 参数 | OpenAI 参数 | 说明 |
|---|---|---|
temperature |
temperature |
行为一致 |
topP |
top_p |
行为一致 |
maxOutputTokens |
max_tokens |
命名不同，功能相同 |
topK |
❌ 不支持 | Gemini 独有 |
presencePenalty |
presence_penalty |
行为一致 |
frequencyPenalty |
frequency_penalty |
行为一致 |
stopSequences |
stop |
命名不同 |
candidateCount |
n |
命名不同 |
seed |
seed |
大致相同 |
{
"systemInstruction": {
"parts": [{"text": "你是一个专业的编程助手，擅长 Python 和 TypeScript。"}]
},
"contents": [
{
"role": "user",
"parts": [
{"text": "请用 Python 写一个斐波那契数列函数。"}
]
},
{
"role": "model",
"parts": [
{"text": "以下是 Python 实现斐波那契数列的几种方式：\n\n1. 递归实现...\n2. 迭代实现...\n3. 生成器实现..."}
]
},
{
"role": "user",
"parts": [
{"text": "请用迭代版本，并加上性能分析。"}
]
}
],
"generationConfig": {
"temperature": 0.2,
"maxOutputTokens": 4096,
"topP": 0.95,
"topK": 40
},
"safetySettings": [
{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
]
}
| 特性 | Gemini | OpenAI |
|---|---|---|
| 消息数组名称 | contents |
messages |
| 消息内容字段 | parts[].text |
content（字符串） |
| 系统提示字段 | systemInstruction |
messages 中的 {"role": "system"} |
| 模型角色值 | model |
assistant |
| 认证方式 | URL 参数 ?key=xxx |
Header Authorization: Bearer |
| 请求方法 | POST + query params | 仅 POST |
| 错误格式 | JSON 错误码 | HTTP 状态码 + JSON |
| 流式格式 | SSE（data: 前缀） |
SSE（同） |
Gemini 的 systemInstruction 是一个独立顶层字段，与 OpenAI 的 system role 有细微行为差异：
| 特性 | Gemini systemInstruction | OpenAI system role |
|---|---|---|
| 多个系统提示 | 支持多个 parts | 仅一个 system 消息 |
| 位置顺序 | 在 contents 之前固定 | 必须在 messages 开头 |
| 上下文窗口占用 | 计入上下文 | 计入上下文 |
| 权重/优先级 | 固定最高 | 固定最高 |
| 动态修改 | 每次请求重新设置 | 只需在 messages 开头 |
实践技巧：Gemini 的 systemInstruction 支持传递多个 parts，可以将不同维度的指令分开：
{
"systemInstruction": {
"parts": [
{"text": "你是一个中文英语教学助手。"},
{"text": "所有回答必须包含原句、翻译、语法解析、例句四个部分。"},
{"text": "使用繁体中文进行解释，但保留英文部分为简体。保持语气友善耐心。"}
]
}
}
Gemini API 提供了比 OpenAI 更透明的安全控制机制：
| 类别 | 说明 | 可调阈值 |
|---|---|---|
HARM_CATEGORY_HARASSMENT |
骚扰内容 | BLOCK_NONE / LOW / MEDIUM / HIGH |
HARM_CATEGORY_HATE_SPEECH |
仇恨言论 | 同上 |
HARM_CATEGORY_SEXUALLY_EXPLICIT |
色情内容 | 同上 |
HARM_CATEGORY_DANGEROUS_CONTENT |
危险内容 | 同上 |
HARM_CATEGORY_CIVIC_INTEGRITY |
选举相关 | 同上（仅部分地域） |
阈值行为对比：
| 阈值 | 对正常输出的影响 | 对敏感内容的拦截 |
|---|---|---|
BLOCK_NONE |
无影响 | 不拦截 |
BLOCK_LOW_AND_ABOVE |
极少量误拦 | 拦截低程度以上 |
BLOCK_MEDIUM_AND_ABOVE（默认） |
少量误拦 | 拦截中等程度以上 |
BLOCK_ONLY_HIGH |
几乎无影响 | 仅拦截严重内容 |
实践建议：对于教育、医疗等需要精确输出的场景，建议将阈值设为 BLOCK_ONLY_HIGH，避免过度过滤导致回答质量下降。
Gemini 对多模态的原生支持是其核心优势。所有模态通过 parts 数组传递。
支持格式：JPEG、PNG、WEBP、HEIC、HEIF
{
"contents": [{
"role": "user",
"parts": [
{"text": "这张图片中有几个物体？请详细描述。"},
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "base64_encoded_image_data"
}
}
]
}]
}
图片 token 用量估算：
| 图片尺寸 | 每张 token 数（近似） |
|---|---|
| 256x256 | ~258 tokens |
| 512x512 | ~1,029 tokens |
| 1024x1024 | ~4,098 tokens |
| 2048x2048 | ~16,386 tokens |
注意：Gemini 会自动将图片缩放到 3072x3072 以内再处理。如果上传超大图片（如 8K 照片），建议预压缩以节省 token。
Gemini 支持直接分析视频内容——这是 GPT-4o 尚未原生支持的差异化能力。
{
"contents": [{
"role": "user",
"parts": [
{"text": "总结这个视频的内容，并列出关键时间轴事件。"},
{
"fileData": {
"mimeType": "video/mp4",
"fileUri": "gs://my-bucket/presentation.mp4"
}
}
]
}]
}
视频处理机制：
gs://）上的对象| 视频时长 | 约消耗 tokens | 建议场景 |
|---|---|---|
| 1 分钟 | 3K-6K | 短视频总结 |
| 5 分钟 | 15K-30K | 教学视频摘要 |
| 10 分钟 | 30K-60K | 会议纪要 |
| 60 分钟 | 180K-360K | 讲座/课程分析 |
Gemini 1.5+ 支持直接处理音频（语音识别 + 理解）：
{
"contents": [{
"role": "user",
"parts": [
{"text": "请转录并总结这段音频内容。"},
{
"inlineData": {
"mimeType": "audio/mp3",
"data": "base64_encoded_audio"
}
}
]
}]
}
支持格式：MP3, WAV, FLAC, OGG, M4A。最长 1 小时。
与 OpenAI 的 function calling 类似但命名方式不同：
{
"tools": [{
"functionDeclarations": [
{
"name": "get_weather",
"description": "获取指定城市的实时天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称，如 '北京'、'上海'"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位"
}
},
"required": ["city"]
}
},
{
"name": "search_hotels",
"description": "搜索酒店信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"},
"checkIn": {"type": "string"},
"checkOut": {"type": "string"},
"guests": {"type": "integer"}
},
"required": ["city", "checkIn", "checkOut"]
}
}
]
}]
}
用户请求 → Gemini 判断需要调用函数
↓
返回 functionCall 类型 response
↓
开发者执行实际函数逻辑
↓
返回 functionResponse 给 Gemini
↓
Gemini 生成最终自然语言回复
关键差异：
| 特性 | Gemini | OpenAI |
|---|---|---|
| 参数名 | functionDeclarations |
functions 或 tools |
| 调用响应 | functionCall parts |
function_call 字段 |
| 执行结果 | functionResponse parts |
function_response |
| 并行调用 | ✅ 支持多 function call | ✅ 支持 |
| 强制调用 | 通过 toolConfig 设置 |
通过 tool_choice: "required" 设置 |
Gemini 流式输出使用 Server-Sent Events，每条消息格式如下：
data: {
"candidates": [{
"content": {
"parts": [{"text": "Hello"}],
"role": "model"
},
"finishReason": 0,
"index": 0,
"safetyRatings": [...]
}]
}
data: {
"candidates": [{
"content": {
"parts": [{"text": " there! How can I"}],
"role": "model"
},
"index": 0
}]
}
data: {
"candidates": [{
"content": {
"parts": [{"text": " help you today?"}],
"role": "model"
},
"finishReason": 1,
"index": 0
}]
}
finishReason 码含义：
| 码值 | 含义 | 说明 |
|---|---|---|
| 0 | FINISH_REASON_UNSPECIFIED | 输出进行中 |
| 1 | STOP | 正常结束（遇到停止符） |
| 2 | MAX_TOKENS | 达到 maxOutputTokens |
| 3 | SAFETY | 被安全过滤器中断 |
| 4 | RECITATION | 检测到抄袭/过度引用 |
| 5 | LANGUAGE | 语言不受支持 |
| 6 | OTHER | 其他原因 |
import json
import requests
def stream_gemini(prompt, model="gemini-2.0-flash", api_key="YOUR_KEY"):
url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:streamGenerateContent?alt=sse&key={api_key}"
payload = {
"contents": [{"role": "user", "parts": [{"text": prompt}]}],
"generationConfig": {"temperature": 0.7, "maxOutputTokens": 4096}
}
response = requests.post(url, json=payload, stream=True)
full_text = ""
for line in response.iter_lines():
if line:
decoded = line.decode('utf-8')
if decoded.startswith('data: '):
try:
data = json.loads(decoded[6:])
for candidate in data.get('candidates', []):
for part in candidate.get('content', {}).get('parts', []):
text = part.get('text', '')
print(text, end='', flush=True)
full_text += text
except json.JSONDecodeError:
pass
return full_text
Gemini 2.0+ 支持原生 JSON 模式，通过 responseMimeType 参数控制：
{
"contents": [{
"role": "user",
"parts": [{"text": "给我 3 个著名物理学家的信息"}]
}],
"generationConfig": {
"responseMimeType": "application/json"
}
}
返回：
{
"candidates": [{
"content": {
"parts": [{"text": "[\n {\"name\": \"阿尔伯特·爱因斯坦\", \"field\": \"相对论\", \"year\": 1905},\n {\"name\": \"理查德·费曼\", \"field\": \"量子电动力学\", \"year\": 1965},\n {\"name\": \"玛丽·居里\", \"field\": \"放射性研究\", \"year\": 1903}\n]"}],
"role": "model"
}
}]
}
重要差异：Gemini 的 JSON 模式输出包装在 parts[0].text 中（作为字符串），不是 OpenAI 的结构化输出字段。需要用 json.loads() 额外解析。
| 模型 | 输入/1M tokens | 输出/1M tokens | 缓存输入/1M tokens |
|---|---|---|---|
| gemini-2.5-pro | $5.00 $20.00 | $1.25 | |
| gemini-2.0-flash | $0.35 $1.05 | $0.0875 | |
| gemini-1.5-pro | $3.50 $10.50 | $0.875 | |
| gemini-1.5-flash | $0.35 $1.05 | $0.0875 | |
| gemini-1.0-pro | $0.50 $1.50 | 不支持 |
| 模型 | 输入价格 | 输出价格 | 性价比 | 推荐场景 |
|---|---|---|---|---|
| gemini-2.0-flash | $0.35 $1.05 | ⭐⭐⭐⭐⭐ | 日常推理首选 | |
| gpt-4o-mini | $0.15 $0.60 | ⭐⭐⭐⭐ | 轻量级任务 | |
| gpt-4o | $2.50 $10.00 | ⭐⭐⭐ | 复杂推理 | |
| claude-3.5-sonnet | $3.00 $15.00 | ⭐⭐⭐ | 长文本分析 | |
| deepseek-v3 | $0.27 $1.10 | ⭐⭐⭐⭐ | 编程场景 |
Gemini 2.0 Flash 在价格上极具竞争力，以 $0.35/$1.05 的价格提供接近顶级的性能。
| HTTP 状态 | 错误原因 | 处理方式 |
|---|---|---|
| 400 | 请求格式错误（缺少必要字段） | 校验请求体 |
| 403 | API Key 无效或配额不足 | 检查 API Key |
| 429 | 超过速率限制 | 指数退避重试 |
| 500 | 服务端错误 | 等待后重试 |
| 503 | 服务暂时不可用 | 切换到其他模型 |
指数退避重试示例：
import time
import random
def gemini_with_retry(payload, model="gemini-2.0-flash", api_key="YOUR_KEY", max_retries=5):
url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={api_key}"
for attempt in range(max_retries):
try:
response = requests.post(url, json=payload)
if response.status_code == 429:
wait = (2 ** attempt) + random.uniform(0, 1)
print(f"Rate limited, waiting {wait:.1f}s...")
time.sleep(wait)
continue
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
if attempt == max_retries - 1:
raise
wait = (2 ** attempt) + random.uniform(0, 1)
print(f"Attempt {attempt+1} failed: {e}, retrying in {wait:.1f}s")
time.sleep(wait)
import google.generativeai as genai
genai.configure(api_key="your-api-key")
model = genai.GenerativeModel(
'gemini-2.0-flash',
system_instruction="你是一个精通数据分析的助手。"
)
# 流式生成
response = model.generate_content(
"请用 Python 实现一个斐波那契数列生成器，并分析时间复杂度。",
generation_config=genai.types.GenerationConfig(
temperature=0.1,
max_output_tokens=2048
),
stream=True
)
for chunk in response:
print(chunk.text, end='')
Gemini 在 v1beta 版本提供了 OpenAI 兼容端点（2025 年更新稳定）：
from openai import OpenAI
client = OpenAI(
api_key="your-gemini-api-key",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
)
response = client.chat.completions.create(
model="gemini-2.0-flash",
messages=[
{"role": "system", "content": "你是一个 Python 专家。"},
{"role": "user", "content": "请解释 Python 的装饰器实现原理。"}
],
temperature=0.3,
max_tokens=2048
)
print(response.choices[0].message.content)
注意事项：Gemini 的 OpenAI 兼容模式是翻译层，部分高级特性（如 topK、safetySettings）无法通过该接口使用。如需使用全部能力，推荐官方 SDK。
import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI("YOUR_API_KEY");
const model = genAI.getGenerativeModel({ model: "gemini-2.0-flash" });
// 多模态示例：传入图片
const imageResp = await fetch("https://example.com/sunset.jpg");
const imageBuffer = await imageResp.arrayBuffer();
const result = await model.generateContent([
"请描述这张图片中的场景",
{
inlineData: {
data: Buffer.from(imageBuffer).toString("base64"),
mimeType: "image/jpeg"
}
}
]);
console.log(result.response.text());
| 维度 | Gemini | OpenAI | 胜出 |
|---|---|---|---|
| 上下文长度 | 1M-2M | 128K | 🏆 Gemini |
| 多模态原生度 | 全模态联合训练 | 图像后期融合 | 🏆 Gemini |
| 视频理解 | ✅ 原生支持 | ❌ 不支持 | 🏆 Gemini |
| 中文编程能力 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 🏆 OpenAI |
| 价格入门级 | $0.35/M tokens $0.15/M tokens | 🏆 OpenAI | |
| 价格旗舰级 | $5.00/M tokens $2.50/M tokens | 🏆 OpenAI | |
| API 生态兼容性 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 🏆 OpenAI |
| 工具/插件生态 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 🏆 OpenAI |
| 结构化输出 | ✅ 2025 新增 | ✅ 原生支持 | ⭐⭐⭐⭐ 持平 |
| 免费额度 | 60次/天 | 免费信用额度 | ⭐⭐⭐⭐ 持平 |
| 函数调用 | ✅ 标准支持 | ✅ 标准支持 | ⭐⭐⭐⭐ 持平 |
gemini-2.0-flash 就足够了，且成本仅为 Pro 的 1/10BLOCK_ONLY_HIGH