API Key 与 Model 选择：成本、能力与场景的权衡

# .env.example（提交到 git）
export GOOGLE_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.0-flash"

# .env（不提交 git，每个开发者独立维护）
export GOOGLE_API_KEY="AIzaSy..."

# 新成员 onboarding
cp .env.example .env
# 编辑 .env，填入自己的 API Key
vim .env
source .env && go run ./cmd/agent

# .github/workflows/deploy.yml
name: Deploy Agent
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        env:
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
          GEMINI_MODEL: ${{ vars.GEMINI_MODEL }}
        run: |
          go build -o agent ./cmd/agent
          ./agent

package config

import (
	"context"
	"fmt"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)

// SecretManagerClient 封装 Secret Manager 操作
type SecretManagerClient struct {
	client *secretmanager.Client
	projectID string
}

// NewSecretManagerClient 创建客户端
func NewSecretManagerClient(ctx context.Context, projectID string) (*SecretManagerClient, error) {
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	return &SecretManagerClient{
		client:    client,
		projectID: projectID,
	}, nil
}

// GetSecret 获取指定版本的 Secret
func (s *SecretManagerClient) GetSecret(ctx context.Context, secretName string) (string, error) {
	req := &secretmanagerpb.AccessSecretVersionRequest{
		Name: fmt.Sprintf("projects/%s/secrets/%s/versions/latest", s.projectID, secretName),
	}

	result, err := s.client.AccessSecretVersion(ctx, req)
	if err != nil {
		return "", fmt.Errorf("failed to access secret %s: %w", secretName, err)
	}

	return string(result.Payload.Data), nil
}

// Close 关闭客户端连接
func (s *SecretManagerClient) Close() error {
	return s.client.Close()
}

func loadAPIKey(ctx context.Context) (string, error) {
	// 本地开发：从环境变量读取
	if key := os.Getenv("GOOGLE_API_KEY"); key != "" {
		return key, nil
	}

	// 生产环境：从 Secret Manager 读取
	sm, err := config.NewSecretManagerClient(ctx, "my-project-id")
	if err != nil {
		return "", err
	}
	defer sm.Close()

	return sm.GetSecret(ctx, "gemini-api-key")
}

package config

import (
	"context"
	"fmt"
	"sync"
	"sync/atomic"
	"time"

	"google.golang.org/genai"
)

// KeyPool 管理多个 API Key，支持轮询和故障转移
type KeyPool struct {
	keys      []string
	current   uint64
	mu        sync.RWMutex
	failures  map[string]int       // 记录每个 Key 的失败次数
	lastUsed  map[string]time.Time // 记录最后使用时间
}

// NewKeyPool 从环境变量创建 Key Pool
func NewKeyPool() *KeyPool {
	keys := []string{}
	for i := 1; ; i++ {
		key := os.Getenv(fmt.Sprintf("GOOGLE_API_KEY_%d", i))
		if key == "" {
			break
		}
		keys = append(keys, key)
	}

	if len(keys) == 0 {
		// 回退到单个 Key
		if key := os.Getenv("GOOGLE_API_KEY"); key != "" {
			keys = append(keys, key)
		}
	}

	return &KeyPool{
		keys:     keys,
		failures: make(map[string]int),
		lastUsed: make(map[string]time.Time),
	}
}

// GetKey 轮询获取下一个可用的 Key
func (p *KeyPool) GetKey() (string, error) {
	p.mu.RLock()
	defer p.mu.RUnlock()

	if len(p.keys) == 0 {
		return "", fmt.Errorf("no API keys available")
	}

	// 原子递增，实现无锁轮询
	idx := atomic.AddUint64(&p.current, 1) % uint64(len(p.keys))
	key := p.keys[idx]

	// 如果某个 Key 连续失败超过 3 次，暂时跳过
	if p.failures[key] > 3 {
		// 找下一个可用的 Key
		for i := 0; i < len(p.keys); i++ {
			idx = (idx + 1) % uint64(len(p.keys))
			key = p.keys[idx]
			if p.failures[key] <= 3 {
				break
			}
		}
	}

	return key, nil
}

// ReportFailure 报告某个 Key 的失败
func (p *KeyPool) ReportFailure(key string) {
	p.mu.Lock()
	defer p.mu.Unlock()
	p.failures[key]++
}

// ReportSuccess 报告某个 Key 的成功，重置失败计数
func (p *KeyPool) ReportSuccess(key string) {
	p.mu.Lock()
	defer p.mu.Unlock()
	p.failures[key] = 0
	p.lastUsed[key] = time.Now()
}

export GOOGLE_API_KEY_1="AIzaSy..."
export GOOGLE_API_KEY_2="AIzaSy..."
export GOOGLE_API_KEY_3="AIzaSy..."

package model

import (
	"context"
	"strings"

	"google.golang.org/adk/model/gemini"
	"google.golang.org/genai"
)

// Router 根据查询特征选择最优模型
type Router struct {
	flashClient *genai.Client
	proClient   *genai.Client
}

// NewRouter 创建模型路由器
func NewRouter(ctx context.Context, apiKey string) (*Router, error) {
	flash, err := gemini.NewModel(ctx, "gemini-2.0-flash", &genai.ClientConfig{APIKey: apiKey})
	if err != nil {
		return nil, err
	}

	pro, err := gemini.NewModel(ctx, "gemini-2.0-pro", &genai.ClientConfig{APIKey: apiKey})
	if err != nil {
		return nil, err
	}

	return &Router{flashClient: flash, proClient: pro}, nil
}

// SelectModel 根据查询内容选择模型
func (r *Router) SelectModel(query string) *genai.Client {
	// 简单关键词启发式路由
	complexIndicators := []string{
		"代码", "code", "debug", "算法", "数学", "证明",
		"分析", "比较", "评估", "优化",
	}

	lowerQuery := strings.ToLower(query)
	for _, indicator := range complexIndicators {
		if strings.Contains(lowerQuery, indicator) {
			return r.proClient
		}
	}

	// 默认使用 Flash（更快更便宜）
	return r.flashClient
}

// 基础版本：通过环境变量切换
modelName := os.Getenv("GEMINI_MODEL")
if modelName == "" {
	modelName = "gemini-2.0-flash"
}

model, err := gemini.NewModel(ctx, modelName, &genai.ClientConfig{
	APIKey: os.Getenv("GOOGLE_API_KEY"),
})

// 进阶版本：支持模型别名和自动降级
modelAlias := os.Getenv("GEMINI_MODEL_ALIAS")
switch modelAlias {
case "fast":
	modelName = "gemini-2.0-flash-lite"
case "balanced":
	modelName = "gemini-2.0-flash"
case "powerful":
	modelName = "gemini-2.0-pro"
default:
	modelName = "gemini-2.0-flash"
}

// 在响应头中，Google API 会返回配额信息
// X-RateLimit-Remaining: 剩余请求数
// X-RateLimit-Reset: 重置时间戳

// 建议在每个请求后记录配额状态
func logQuotaStatus(header http.Header) {
	remaining := header.Get("X-RateLimit-Remaining")
	reset := header.Get("X-RateLimit-Reset")
	if remaining != "" {
		log.Printf("[QUOTA] Remaining: %s, Reset: %s", remaining, reset)
	}
}

package ratelimit

import (
	"context"
	"time"

	"golang.org/x/time/rate"
)

// Limiter 封装速率限制器
type Limiter struct {
	limiter *rate.Limiter
}

// NewLimiter 创建限流器
// r: 每秒允许的请求数
// b: 桶容量（突发流量缓冲）
func NewLimiter(r rate.Limit, b int) *Limiter {
	return &Limiter{
		limiter: rate.NewLimiter(r, b),
	}
}

// Wait 等待获取令牌
func (l *Limiter) Wait(ctx context.Context) error {
	return l.limiter.Wait(ctx)
}

// 使用示例：限制每分钟 50 请求（留 10 请求缓冲）
// limiter := ratelimit.NewLimiter(rate.Every(time.Minute/50), 10)
// if err := limiter.Wait(ctx); err != nil { return err }

package retry

import (
	"context"
	"fmt"
	"time"

	"google.golang.org/genai"
)

// ExponentialBackoff 实现指数退避重试
func ExponentialBackoff(ctx context.Context, operation func() error, maxRetries int) error {
	var err error
	baseDelay := time.Second

	for i := 0; i < maxRetries; i++ {
		err = operation()
		if err == nil {
			return nil
		}

		// 检查是否是配额错误
		if !isQuotaError(err) {
			return err // 非配额错误，立即返回
		}

		// 计算退避时间
		delay := baseDelay * time.Duration(1<<i)
		if delay > 30*time.Second {
			delay = 30 * time.Second
		}

		log.Printf("[RETRY] Quota exceeded, retrying in %v (attempt %d/%d)", delay, i+1, maxRetries)

		select {
		case <-time.After(delay):
			continue
		case <-ctx.Done():
			return ctx.Err()
		}
	}

	return fmt.Errorf("max retries exceeded: %w", err)
}

func isQuotaError(err error) bool {
	if err == nil {
		return false
	}
	errStr := err.Error()
	return contains(errStr, "RESOURCE_EXHAUSTED") ||
		contains(errStr, "Quota exceeded") ||
		contains(errStr, "429")
}

func contains(s, substr string) bool {
	return strings.Contains(s, substr)
}

#!/bin/bash
echo "=== API 连通性诊断 ==="
echo "1. 检查环境变量:"
echo "GOOGLE_API_KEY length: ${#GOOGLE_API_KEY}"

echo "2. 检查网络连通性:"
curl -s -o /dev/null -w "%{http_code}" https://generativelanguage.googleapis.com/v1beta/models
echo ""

echo "3. 检查代理设置:"
echo "HTTPS_PROXY: $HTTPS_PROXY"

echo "4. 测试 API 调用:"
curl -s "https://generativelanguage.googleapis.com/v1beta/models?key=$GOOGLE_API_KEY" | head -c 200
echo ""

// 安全的模型选择逻辑
func selectProductionModel() string {
	// 优先使用稳定版本
	if model := os.Getenv("GEMINI_MODEL_STABLE"); model != "" {
		return model
	}
	// 回退到最稳定的默认选项
	return "gemini-2.0-flash"
}

// 在每次模型调用后记录 token 使用量
func logUsage(response *genai.GenerateContentResponse) {
	if response.UsageMetadata != nil {
		log.Printf("[USAGE] Input: %d tokens, Output: %d tokens, Total: %d tokens",
			response.UsageMetadata.PromptTokenCount,
			response.UsageMetadata.CandidatesTokenCount,
			response.UsageMetadata.TotalTokenCount)
	}
}

# 设置每日预算告警（通过 gcloud CLI）
gcloud billing budgets create \
  --billing-account=YOUR_BILLING_ACCOUNT \
  --display-name="Gemini API Daily Budget" \
  --budget-amount=10USD \
  --threshold-rule=percent=80 \
  --all-updates-rule-pubsub-topic=projects/my-project/topics/budget-alerts