07d - API 集成指南

# 方式 A：环境变量（推荐）
export GEMINI_API_KEY="your-api-key-here"
 
# 方式 B：.env 文件（配合 dotenv 库）
echo 'GEMINI_API_KEY=your-api-key-here' >> .env
# 确保 .env 已加入 .gitignore
echo '.env' >> .gitignore

# 1. 在 Google Cloud Console 创建 OAuth 2.0 客户端 ID
#    APIs & Services → Credentials → Create Credentials → OAuth client ID
 
# 2. 下载客户端配置文件
#    保存为 client_secret.json
 
# 3. 使用 gcloud 进行本地 OAuth 认证
gcloud auth application-default login

# Python：使用 OAuth 认证访问 Gemini API（通过 Vertex AI）
from google import genai
 
# ADC（Application Default Credentials）自动检测本地 OAuth 凭证
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)
 
response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="你好，请介绍一下你自己。"
)
print(response.text)

# 1. 创建 Service Account
gcloud iam service-accounts create gemini-api-sa \
    --display-name="Gemini API Service Account"
 
# 2. 授予 Vertex AI 权限
gcloud projects add-iam-policy-binding your-project-id \
    --member="serviceAccount:gemini-api-sa@your-project-id.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"
 
# 3. 生成密钥文件
gcloud iam service-accounts keys create key.json \
    --iam-account=gemini-api-sa@your-project-id.iam.gserviceaccount.com
 
# 4. 设置环境变量
export GOOGLE_APPLICATION_CREDENTIALS="./key.json"

# Python：使用 Service Account 认证
from google import genai
 
# 自动读取 GOOGLE_APPLICATION_CREDENTIALS 环境变量
client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)
 
response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="分析以下代码的安全漏洞..."
)

你是一位 DevOps 工程师，请帮我为以下场景选择最合适的 Gemini API 认证方式：

场景描述：[描述你的应用场景，如：一个 SaaS 产品的后端服务，需要调用 Gemini API 处理用户上传的文档]

请考虑以下因素：
1. 安全性要求
2. 部署环境（本地/云端/容器）
3. 团队规模
4. 是否需要 Vertex AI 的企业功能

输出：推荐的认证方式、配置步骤、安全注意事项。

场景：AI 代码审查助手
- 每次请求：平均 5,000 输入 tokens + 2,000 输出 tokens
- 日请求量：1,000 次
- 月请求量：30,000 次

方案 A：全部使用 Gemini 3.1 Pro
  输入：30,000 × 5,000 / 1M × $2.00 = $300
  输出：30,000 × 2,000 / 1M × $12.00 = $720
  月总计：$1,020

方案 B：简单请求用 Flash，复杂请求用 Pro（70/30 分流）
  Flash 输入：21,000 × 5,000 / 1M × $0.50 = $52.50
  Flash 输出：21,000 × 2,000 / 1M × $3.00 = $126
  Pro 输入：9,000 × 5,000 / 1M × $2.00 = $90
  Pro 输出：9,000 × 2,000 / 1M × $12.00 = $216
  月总计：$484.50（节省 52%）

方案 C：方案 B + Batch API（非实时部分）
  月总计：约 $290（节省 72%）

import time
import random
from google import genai
 
client = genai.Client(api_key="your-api-key")
 
def call_with_retry(prompt: str, max_retries: int = 5) -> str:
    """带指数退避的 API 调用"""
    for attempt in range(max_retries):
        try:
            response = client.models.generate_content(
                model="gemini-3.1-pro",
                contents=prompt
            )
            return response.text
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"速率限制，等待 {wait_time:.1f}s 后重试...")
                time.sleep(wait_time)
            else:
                raise
    return ""

import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
async function callWithRetry(prompt: string, maxRetries = 5): Promise<string> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await ai.models.generateContent({
        model: "gemini-3.1-pro",
        contents: prompt,
      });
      return response.text ?? "";
    } catch (error: any) {
      if (error?.status === 429 && attempt < maxRetries - 1) {
        const waitTime = Math.pow(2, attempt) + Math.random();
        console.log(`速率限制，等待 ${waitTime.toFixed(1)}s 后重试...`);
        await new Promise((r) => setTimeout(r, waitTime * 1000));
      } else {
        throw error;
      }
    }
  }
  return "";
}

# Python
pip install -U google-genai
 
# Node.js / TypeScript
npm install @google/genai
 
# Go
go get google.golang.org/genai

import os
from google import genai
 
# 创建客户端（Developer API）
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# 基础文本生成
response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="请用 Python 实现一个线程安全的 LRU 缓存。"
)
print(response.text)
 
# 查看 token 使用量
print(f"输入 tokens: {response.usage_metadata.prompt_token_count}")
print(f"输出 tokens: {response.usage_metadata.candidates_token_count}")
print(f"总 tokens: {response.usage_metadata.total_token_count}")

import { GoogleGenAI } from "@google/genai";
 
// 创建客户端
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
// 基础文本生成
const response = await ai.models.generateContent({
  model: "gemini-3.1-pro",
  contents: "请用 TypeScript 实现一个线程安全的 LRU 缓存。",
});
console.log(response.text);
 
// 查看 token 使用量
console.log(`输入 tokens: ${response.usageMetadata?.promptTokenCount}`);
console.log(`输出 tokens: ${response.usageMetadata?.candidatesTokenCount}`);
console.log(`总 tokens: ${response.usageMetadata?.totalTokenCount}`);

import os
from google import genai
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# 流式生成——逐块返回，适合实时展示
for chunk in client.models.generate_content_stream(
    model="gemini-3.1-pro",
    contents="请详细解释 Rust 的所有权系统。"
):
    print(chunk.text, end="", flush=True)
print()  # 换行

import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
// 流式生成
const stream = await ai.models.generateContentStream({
  model: "gemini-3.1-pro",
  contents: "请详细解释 Rust 的所有权系统。",
});
 
for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? "");
}
console.log(); // 换行

import os
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="审查以下 Python 代码的安全性：\n```python\nimport os\nos.system(input('Enter command: '))\n```",
    config=types.GenerateContentConfig(
        system_instruction="你是一位资深安全工程师，专注于代码安全审查。对每个发现的问题，给出严重等级（Critical/High/Medium/Low）、问题描述和修复建议。",
        temperature=0.2,          # 低温度 = 更确定性的输出
        max_output_tokens=4096,   # 最大输出长度
        top_p=0.95,
        top_k=40,
        response_mime_type="application/json",  # 结构化 JSON 输出
    )
)
print(response.text)

import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
const response = await ai.models.generateContent({
  model: "gemini-3.1-pro",
  contents: '审查以下 Python 代码的安全性：\n```python\nimport os\nos.system(input("Enter command: "))\n```',
  config: {
    systemInstruction:
      "你是一位资深安全工程师，专注于代码安全审查。对每个发现的问题，给出严重等级（Critical/High/Medium/Low）、问题描述和修复建议。",
    temperature: 0.2,
    maxOutputTokens: 4096,
    topP: 0.95,
    topK: 40,
    responseMimeType: "application/json",
  },
});
console.log(response.text);

from google import genai
from google.genai import types
import os
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# 高思考模式——适合复杂推理任务
response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="证明：对于所有正整数 n，1² + 2² + ... + n² = n(n+1)(2n+1)/6",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH")
    )
)
 
# 查看思考过程（如果可用）
for part in response.candidates[0].content.parts:
    if part.thought:
        print(f"💭 思考过程:\n{part.text}\n")
    else:
        print(f"📝 最终回答:\n{part.text}")

import { GoogleGenAI } from "@google/genai";
 
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
 
const response = await ai.models.generateContent({
  model: "gemini-3.1-pro",
  contents: "证明：对于所有正整数 n，1² + 2² + ... + n² = n(n+1)(2n+1)/6",
  config: {
    thinkingConfig: { thinkingLevel: "HIGH" },
  },
});
 
// 查看思考过程
for (const part of response.candidates?.[0]?.content?.parts ?? []) {
  if (part.thought) {
    console.log(`💭 思考过程:\n${part.text}\n`);
  } else {
    console.log(`📝 最终回答:\n${part.text}`);
  }
}

from google import genai
from google.genai import types
import os
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# 上传大型代码库文件
code_file = client.files.upload(file="./large_codebase.zip")
 
# 创建缓存（有效期 2 小时）
cache = client.caches.create(
    model="gemini-3.1-pro",
    config=types.CreateCachedContentConfig(
        display_name="codebase-review",
        system_instruction="你是一位高级代码审查员。基于提供的代码库回答问题。",
        contents=[code_file],
        ttl="7200s",  # 2 小时有效期
    )
)
 
# 第一轮：架构分析（缓存命中，输入成本降低 90%）
r1 = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="请分析这个代码库的整体架构，画出模块依赖图。",
    config=types.GenerateContentConfig(cached_content=cache.name)
)
print(r1.text)
 
# 第二轮：安全审查（同一缓存，无需重新上传）
r2 = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="请检查代码中的安全漏洞，重点关注 SQL 注入和 XSS。",
    config=types.GenerateContentConfig(cached_content=cache.name)
)
print(r2.text)
 
# 缓存存储费用：$4.50/1M tokens/小时
# 对比直接输入：如果代码库 500K tokens，每次查询输入成本 $2.00
# 使用缓存：首次 $2.00 + 后续每次 $0.10 + 存储 $2.25/小时

from google import genai
from google.genai import types
import os, json
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# 定义工具
tools = [
    types.Tool(function_declarations=[
        types.FunctionDeclaration(
            name="get_weather",
            description="获取指定城市的当前天气信息",
            parameters=types.Schema(
                type="OBJECT",
                properties={
                    "city": types.Schema(type="STRING", description="城市名称"),
                    "unit": types.Schema(
                        type="STRING",
                        enum=["celsius", "fahrenheit"],
                        description="温度单位"
                    ),
                },
                required=["city"],
            ),
        ),
        types.FunctionDeclaration(
            name="search_flights",
            description="搜索航班信息",
            parameters=types.Schema(
                type="OBJECT",
                properties={
                    "origin": types.Schema(type="STRING", description="出发城市"),
                    "destination": types.Schema(type="STRING", description="目的城市"),
                    "date": types.Schema(type="STRING", description="出发日期 YYYY-MM-DD"),
                },
                required=["origin", "destination", "date"],
            ),
        ),
    ])
]
 
response = client.models.generate_content(
    model="gemini-3.1-pro",
    contents="我下周三想从北京飞上海，帮我查一下航班和上海的天气。",
    config=types.GenerateContentConfig(tools=tools)
)
 
# 处理函数调用
for part in response.candidates[0].content.parts:
    if part.function_call:
        print(f"调用函数: {part.function_call.name}")
        print(f"参数: {json.dumps(dict(part.function_call.args), ensure_ascii=False)}")

from google import genai
 
# 方式 A：Developer API（API Key 认证）
client_dev = genai.Client(api_key="your-api-key")
 
# 方式 B：Vertex AI（ADC / Service Account 认证）
client_vertex = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1"
)
 
# 两种方式的调用代码完全相同
for client in [client_dev, client_vertex]:
    response = client.models.generate_content(
        model="gemini-3.1-pro",
        contents="Hello, Gemini!"
    )
    print(response.text)

import { GoogleGenAI } from "@google/genai";
 
// 方式 A：Developer API
const aiDev = new GoogleGenAI({ apiKey: "your-api-key" });
 
// 方式 B：Vertex AI
const aiVertex = new GoogleGenAI({
  vertexai: true,
  project: "your-project-id",
  location: "us-central1",
});
 
// 调用代码完全相同
for (const ai of [aiDev, aiVertex]) {
  const response = await ai.models.generateContent({
    model: "gemini-3.1-pro",
    contents: "Hello, Gemini!",
  });
  console.log(response.text);
}

from google import genai
import os
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# 预估 token 数量
count_response = client.models.count_tokens(
    model="gemini-3.1-pro",
    contents="这是一段需要预估 token 数量的文本..."
)
print(f"预估 token 数: {count_response.total_tokens}")
 
# 成本计算
input_tokens = count_response.total_tokens
estimated_output = 2000  # 预估输出 tokens
input_cost = input_tokens / 1_000_000 * 2.00   # $2.00/1M
output_cost = estimated_output / 1_000_000 * 12.00  # $12.00/1M
print(f"预估成本: ${input_cost + output_cost:.4f}")

你的任务是什么？
│
├─ 复杂推理 / 数学 / 竞赛编程
│  └─ → Gemini 3.1 Pro（thinking_level: HIGH）
│
├─ Agentic 工作流 / 自主编码
│  └─ → Gemini 3.1 Pro 或 3 Pro
│
├─ 多模态理解（图像/视频/音频）
│  ├─ 需要精确分析 → Gemini 3 Pro
│  └─ 够用就好 → Gemini 3 Flash
│
├─ 长文档分析（>200K tokens）
│  ├─ 预算充足 → Gemini 3.1 Pro
│  └─ 控制成本 → Gemini 2.5 Flash
│
├─ 实时对话 / 低延迟
│  └─ → Gemini 3 Flash 或 2.5 Flash
│
├─ 大规模批量处理
│  ├─ 需要高质量 → Gemini 3.1 Pro + Batch API
│  └─ 简单任务 → Flash-Lite + Batch API
│
└─ 学习 / 原型验证（免费）
   └─ → Gemini 2.5 Flash（免费层）

import os, json
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
def review_code_changes(diff: str, file_path: str) -> dict:
    """使用 Gemini 3.1 Pro 审查代码变更"""
    
    # 预估 token 数量
    count = client.models.count_tokens(
        model="gemini-3.1-pro",
        contents=diff
    )
    
    # 根据 diff 大小选择模型
    model = "gemini-3.1-pro" if count.total_tokens > 5000 else "gemini-3-flash"
    
    response = client.models.generate_content(
        model=model,
        contents=f"请审查以下代码变更（文件：{file_path}）：\n\n```diff\n{diff}\n```",
        config=types.GenerateContentConfig(
            system_instruction="""你是一位资深代码审查员。请从以下维度审查代码：
1. 安全性（注入、泄露、权限）
2. 性能（N+1、内存泄漏、阻塞）
3. 可维护性（命名、复杂度、重复）
4. 正确性（边界条件、错误处理）
 
对每个发现返回 JSON 格式：
{
  "issues": [{"severity": "high/medium/low", "line": 行号, "description": "描述", "suggestion": "建议"}],
  "summary": "总体评价",
  "approve": true/false
}""",
            temperature=0.1,
            response_mime_type="application/json",
            thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
        )
    )
    
    result = json.loads(response.text)
    result["model_used"] = model
    result["tokens_used"] = response.usage_metadata.total_token_count
    return result
 
# 使用示例
diff_content = """
- password = request.form['password']
+ password = hashlib.sha256(request.form['password'].encode()).hexdigest()
+ if len(password) < 8:
+     return "Password too short", 400
"""
 
review = review_code_changes(diff_content, "auth/login.py")
print(json.dumps(review, ensure_ascii=False, indent=2))

# 策略 1：本地 Gemma 3 + 云端 Gemini 混合使用
# 安装 Ollama 并下载 Gemma 3
ollama pull gemma3:27b    # 27B 参数，需要 16GB+ 内存
ollama pull gemma3:12b    # 12B 参数，需要 8GB+ 内存
ollama pull gemma3:4b     # 4B 参数，需要 4GB+ 内存
 
# 日常开发用本地 Gemma 3（无限制）
ollama run gemma3:27b "请用 Python 实现一个 LRU 缓存"
 
# 复杂任务用云端 Gemini 2.5 Pro 免费层
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"分析这段代码的安全漏洞..."}]}]}'

策略 2：免费层速率限制下的开发工作流

开发阶段（$0 成本）：
├── Prompt 调试 → Google AI Studio 在线 Playground（无需 API 调用）
├── 本地测试   → Ollama + Gemma 3 27B（无限制）
├── 复杂推理   → Gemini 2.5 Pro 免费层（5 RPM，够用）
├── 快速迭代   → Gemini 2.5 Flash 免费层（10 RPM）
└── 图像生成   → Gemini 图像 API 免费层（~500 张/天）

生产阶段（按需付费）：
├── 升级到付费层（绑定信用卡即可，按用量计费）
├── 使用 Gemini 3 Flash（$0.50/1M 输入，性价比极高）
└── 批量任务用 Batch API（额外 50% 折扣）