跳到主要内容

Gemini AI 集成详解

目录​

  1. Gemini AI 概述
  2. API 调用架构
  3. Prompt Engineering（提示词工程）
  4. 重试机制与错误处理
  5. Token 使用与成本控制
  6. 图像生成集成

Gemini AI 概述​

什么是 Google Gemini？​

Google Gemini 是 Google 开发的大型语言模型（Large Language Model，LLM），能够理解和生成自然语言文本。在本项目中，Gemini 扮演着"智能分析师"的角色，负责：

  1. 数据分析：理解 Excel 或 Google Sheet 中的结构化数据
  2. 洞察生成：基于数据生成专业的市场分析洞察
  3. 内容创作：生成幻灯片文案、人群画像描述、战略建议等
  4. 图像生成：通过 Imagen 4.0 生成场景示意图

为什么选择 Gemini？​

  1. Google 生态集成：作为 Google 内部项目，使用 Gemini 可以享受更好的技术支持和资源
  2. 多模态能力：支持文本生成和图像生成，满足项目的多样化需求
  3. API 稳定性：Google 提供的 API 服务稳定可靠，适合生产环境使用
  4. 成本可控：相比其他 AI 服务，Gemini 的定价策略更适合企业内部使用

在本项目中的使用场景​

  • 市场机会分析：分析市场数据，生成四象限分析和战略建议
  • 人群信号分析：基于用户行为数据，生成人群标签推荐和人群画像段落
  • 受众画像幻灯片：解析和翻译受众画像数据，生成幻灯片内容和图像描述

API 调用架构​

前后端分离设计​

系统采用前后端分离的架构，Gemini API 调用完全在后端进行，前端只负责发送请求和展示结果。

设计优势：

  • 安全性：API Key 不会暴露在前端代码中
  • 统一管理：所有 AI 调用逻辑集中管理，便于维护和优化
  • 错误处理：后端可以实现统一的重试和错误处理机制

调用流程​

sequenceDiagram
    participant FE as 前端 (React)
    participant BE as 后端 (Node.js)
    participant GA as Google Gemini API

    FE->>BE: 1. 发送分析请求<br>(包含数据、Prompt、配置)
    BE->>BE: 2. 验证请求参数
    BE->>BE: 3. 构建 Gemini API 请求
    BE->>GA: 4. 调用 Gemini API<br>(带重试机制)
    GA-->>BE: 5. 返回 AI 生成结果
    BE->>BE: 6. 解析和验证结果
    BE-->>FE: 7. 返回结构化数据
    FE->>FE: 8. 渲染结果到页面

后端 API 端点​

系统提供以下后端 API 端点：

1. 文本生成 API​

端点：POST /api/gemini/generate

请求参数：

{
  model: string;              // Gemini 模型名称，如 "gemini-2.5-pro"
  prompt: string;             // 提示词（包含任务描述和数据）
  temperature?: number;       // 温度参数（0-1），控制输出的随机性
  maxTokens?: number;         // 最大输出 token 数
  responseMimeType?: string;  // 响应格式，如 "application/json"
}

响应格式：

{
  text: string;               // AI 生成的文本内容
  tokenUsage?: {              // Token 使用统计
    promptTokenCount?: number;
    candidatesTokenCount?: number;
    totalTokenCount?: number;
  };
  executionTime: number;      // 执行时间（毫秒）
  retryCount: number;         // 重试次数
}

2. 图像生成 API​

端点：POST /api/gemini/generate-image

请求参数：

{
  model: string;              // 图像生成模型，如 "imagen-4.0"
  prompt: string;             // 图像描述提示词
  aspectRatio?: string;       // 宽高比，如 "1:1"
  personGeneration?: string;  // 人物生成模式
}

响应格式：

{
  imageBase64: string;       // Base64 编码的图像数据
  tokenUsage?: {              // Token 使用统计
    promptTokenCount?: number;
    candidatesTokenCount?: number;
    totalTokenCount?: number;
  };
  executionTime: number;     // 执行时间（毫秒）
  retryCount: number;         // 重试次数
}

前端调用封装​

前端使用 backendGeminiService.ts 封装了所有后端 API 调用，提供了统一的接口和错误处理。

核心函数：

// 文本生成（带重试）
export async function callBackendGeminiWithRetry(
  request: BackendGeminiRequest,
  maxRetries: number = 3,
  onRetry?: (attempt: number, maxRetries: number, delay: number) => void
): Promise<BackendGeminiResponse>

// 图像生成（带重试）
export async function callBackendGeminiImageGenerationWithRetry(
  request: BackendGeminiImageRequest,
  maxRetries: number = 3,
  onRetry?: (attempt: number, maxRetries: number, delay: number) => void
): Promise<BackendGeminiImageResponse>

Prompt Engineering（提示词工程）​

什么是 Prompt Engineering？​

Prompt Engineering（提示词工程）是指设计和优化输入给 AI 模型的指令（Prompt），以获得最佳的输出结果。在本项目中，Prompt 的质量直接决定了 AI 生成内容的质量和准确性。

一个好的 Prompt，不是简单地向 AI 提问，而是为它设定一个角色、一套详细的行动指南、以及一个清晰的输出格式。它就像是为 AI 编写的一部"行动剧本"。

Prompt 设计原则​

1. 明确任务目标​

Prompt 应该清楚地说明 AI 需要完成的任务，包括：

  • 角色定义：AI 扮演什么角色（如"资深 Google Digital Marketing Strategist"）
  • 任务描述：具体要完成什么任务
  • 输出要求：期望的输出格式和内容

示例（市场机会分析）：

你是一位资深的 Google Digital Marketing Strategist（DMS），正在进行一个完整的"市场机会分析"。

你的任务是基于提供的市场数据，识别不同市场（国家/地区）在不同品类上的商业机会，并生成专业的分析报告。

输出要求：
1. 必须输出有效的 JSON 格式
2. 包含市场分类（机会市场、挑战市场、潜力市场、蓝海市场）
3. 每个市场包含优先级分析和战略建议

2. 提供上下文信息​

Prompt 应该包含足够的上下文信息，帮助 AI 理解数据含义和业务背景。

示例：

行业名称：${industryName}
分析周期：${popPeriod}
输出语言：${outputLanguage}

数据字段说明：
- CPC：每次点击成本，数值越高表示竞争越激烈
- Clicks：点击量，表示市场需求强度
- Median Demand：市场需求中位数
- Median Competition：市场竞争中位数

3. 定义输出格式​

明确指定输出格式，确保 AI 生成的内容可以被程序正确解析。

示例（JSON 格式要求）：

输出格式要求：
- 必须输出一个有效的 JSON 对象（不是数组）
- 必须包含以下字段：
  * subtitle: string（副标题）
  * priority1: { title: string, description: string, highlights: string[], strategies: string[] }
  * priority2: { title: string, description: string, highlights: string[], strategies: string[] }
- 所有字符串字段不能为空
- JSON 格式必须正确，可以被 JSON.parse() 解析

4. 提供示例​

在 Prompt 中提供示例，帮助 AI 理解期望的输出格式和内容质量。

示例：

示例 JSON 格式：
{
  "subtitle": "基于高需求、低竞争的市场特征，我们识别出以下机会市场...",
  "priority1": {
    "title": "第一优先级",
    "description": "基于高需求、低竞争的市场特征",
    "highlights": ["美国市场在电子产品类别表现突出", "CPC 相对较低，竞争压力小"],
    "strategies": ["加大广告投入", "优化关键词策略"]
  }
}

实际案例：市场机会分析的 Prompt 设计​

在"市场机会分析"功能中，我们设计了两套核心 Prompt，分别用于数据处理和图表总结。让我们详细拆解这些 Prompt 的设计巧思。

Prompt 1：数据处理与战略建议生成​

这个 Prompt 是整个功能的第一步，也是最关键的一步。它的核心任务是将用户上传的原始数据，转化为结构化的、富有洞察的分析结果，并生成初步的战略建议。

设计要点拆解：

  1. 角色扮演：

    你是一位谷歌广告 (Google Ads) 营销策略顾问。你的任务是分析所提供的市场数据，帮助客户确定国家扩张的优先顺序。

    • 巧思解读：我们首先为 AI 设定了一个清晰的身份——谷歌广告营销策略顾问。这不仅仅是一个称呼，它能有效地激活 AI 模型内部关于市场营销、数据分析和商业策略的知识，让它的回答更专业、更贴近我们的业务场景。

  2. 输入数据说明：

    输入数据为 JSON 对象数组... "Clicks" 代表市场需求大小... "CPC" 代表市场竞争激烈程度。

    • 巧思解读：我们明确地告诉 AI，它将收到的数据是什么格式，以及每个关键字段（如 Clicks, CPC）的商业含义。这避免了 AI 对数据产生误解，确保了分析的准确性。

  3. 严格的、分步骤的行动指令：

    请严格按照以下步骤操作... 1. 过滤掉 "All selected query entities" 的所有行。 2. 对于每个唯一的 "Query Set Name"... a. 首先，根据 "Clicks" 从高到低排序，找出该品类排名前 50 的国家。 b. 基于这前 50 个国家的数据，计算 ... 中位数。 c. 接下来 ... 选出 "Clicks" 最高的前 \${topN} 个国家。 d. 为这前 \${topN} 个国家中的每一个，创建一个新的 JSON 对象...

    • 巧思解读：这是整个 Prompt 的核心。我们没有给 AI 一个模糊的"请帮我分析一下"的指令，而是将资深分析师的完整分析流程，拆解成了一系列机器可以精确执行的、毫无歧义的步骤。这包括了数据清洗、计算基准（中位数）、筛选核心目标，以及最终生成结构化的输出。这套流程，本身就是团队宝贵的知识资产。

  4. 定义分析模型（四象限）：

    - "属于哪个市场": 根据以上两个指标生成的字符串： - 高竞争=1 & 高需求=1 -> "机会市场" - 高竞争=1 & 高需求=0 -> "挑战市场" - 高竞争=0 & 高需求=0 -> "潜力市场" - 高竞争=0 & 高需求=1 -> "蓝海市场"

    • 巧思解读：我们在这里定义了我们自己的分析模型。通过让 AI 计算每个国家的需求和竞争度是否高于中位数，我们教会了 AI 如何使用经典的"四象限分析法"来对市场进行分类。这是将人类的商业智慧赋予机器的典型范例。

  5. 结构化的输出要求：

    4. 最后，用 \${outputLanguage} 提供一段约 350-500 字的总体战略建议。战略建议必须严格分为两段，格式如下... **第一段（结论性内容...）**：... **第二段（数据支撑说明...）**：...

    • 巧思解读：我们不仅要求 AI 进行分析，还对它的输出格式提出了极其严格的要求。我们要求它生成结构化的文本，包含"结论"和"数据支撑"两部分，并对每一部分的字数和内容要点都做了详细规定。这确保了 AI 生成的内容可以直接用于制作报告，而不是一段杂乱无章的文字。我们甚至考虑到了"印度市场"的特殊性，并将其作为规则写入 Prompt，这是领域知识深度嵌入的体现。

Prompt 2：图表总结生成​

当第一步的数据处理完成后，前端会根据结果生成一个可视化的气泡图。第二个 Prompt 的任务，就是让 AI "看懂"这张图，并为它撰写出画龙点睛的、富有商业洞察力的文字总结。

设计要点：

  • 明确的角色：你是一位专业的谷歌广告市场策略师...
  • 严格的输出格式：要求必须输出一个包含 slideTitle, priority1_highlight 等字段的 JSON 对象，这使得前端可以直接读取并填充到幻灯片模板的对应位置。
  • 精细的规则约束：
    • 严禁在分析中出现任何具体的数字：强制 AI 使用定性的、更具商业洞察力的语言（如"高于中位数"、"增速强劲"）进行描述，而不是简单地复述数字。
    • 关于印度 (India) 的分析：再次强调了印度市场的特殊性，确保 AI 的建议既基于数据，又符合真实的商业环境。
    • 明确的优先级定义：我们直接告诉 AI，如何根据数据在不同象限的位置来定义"第一优先级"和"第二优先级"市场，并给出了针对性的策略建议方向。

设计巧思总结：

通过以上拆解，您可以看到，CSA 3A (InsightHub) 的"智能"，并非空穴来风。它源于项目创始人将自己作为数据策略师的专业经验、分析框架和领域知识，通过 Prompt Engineering 这种全新的方式，系统性地"编码"和"教授"给了 Gemini AI。

这背后所付出的思考、设计和反复调试，是项目能够产出高质量、标准化报告的核心，也是本项目最大的技术亮点和价值所在。这也为我们未来的协作提供了一个清晰的思路：当我们需要优化分析逻辑或者增加新的分析维度时，很多时候我们首先需要优化的，正是这些驱动着 AI 大脑的 Prompt。

Prompt 模板管理​

系统使用 PromptManager 功能来管理 Prompt 模板，支持：

  1. 预设模板：系统提供的默认模板
  2. 自定义模板：用户可以创建和编辑自己的模板
  3. 模板版本管理：记录模板的创建和更新时间
  4. 模板共享：团队成员可以共享模板

模板存储格式（YAML）：

id: geo-analysis-preset-default-zh
name: 市场机会分析模板（简体中文）
workflowType: geo-analysis
isPreset: true
creatorName: System
createdAt: '2025-01-01T00:00:00.000Z'
prompts:
  dataProcessingPrompt:
    editable: true
    content: |
      你是一位资深的 Google Digital Marketing Strategist...
  chartSummaryPrompt:
    editable: true
    content: |
      基于以下市场数据，生成专业的分析报告...

重试机制与错误处理​

为什么需要重试机制？​

Gemini API 调用可能因为以下原因失败：

  • 服务过载：API 服务暂时不可用（503 错误）
  • 速率限制：请求频率超过限制（429 错误）
  • 网络问题：网络连接不稳定或超时
  • 临时错误：服务端的临时故障

重试机制可以自动处理这些临时性错误，提高系统的稳定性和用户体验。

错误分类​

系统将错误分为以下几类：

错误类型HTTP 状态码是否可重试重试延迟
服务过载503✅ 是5 秒
速率限制429✅ 是10 秒
服务不可用UNAVAILABLE✅ 是3 秒
网络错误ECONNREFUSED / ETIMEDOUT✅ 是2 秒
其他错误其他❌ 否-

指数退避策略​

系统使用指数退避（Exponential Backoff）策略来避免对 API 服务造成过大压力。

退避算法：

  • 初始延迟：2 秒
  • 每次重试：延迟时间翻倍（2 秒 → 4 秒 → 8 秒 → ...）
  • 最大重试次数：10 次（文本生成）或 3 次（图像生成）

实现代码（server/geminiService.ts）：

export async function callGemini(
  config: GeminiCallConfig,
  apiKey: string,
  maxRetries: number = 10,
  initialDelay: number = 2000,
  context?: { sessionUuid?: string; featureType?: string; userId?: string }
): Promise<GeminiCallResult> {
  let attempt = 0;
  let delay = initialDelay;
  const startTime = Date.now();

  while (attempt < maxRetries) {
    try {
      // 调用 Gemini API
      const response = await ai.models.generateContent({...});
      return { text: response.text, ... };
    } catch (error: any) {
      attempt++;
      const errorInfo = classifyError(error);

      // 如果不可重试或已达到最大重试次数，抛出错误
      if (!errorInfo.retryable || attempt >= maxRetries) {
        throw new GeminiCallError(...);
      }

      // 等待后重试（指数退避）
      const retryAfter = errorInfo.retryAfter || delay;
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      delay *= 2; // 延迟时间翻倍
    }
  }
}

错误日志记录​

系统会记录详细的错误日志，便于问题诊断和性能优化。

日志格式（符合 Google Cloud Run 的 JSON 日志格式）：

{
  "timestamp": "2025-01-XXT12:00:00.000Z",
  "severity": "WARNING",
  "message": "Gemini API 调用失败 (尝试 2/10)",
  "model": "gemini-2.5-pro",
  "sessionUuid": "abc123",
  "featureType": "geo-analysis",
  "attempt": 2,
  "error": "Service temporarily unavailable",
  "errorCode": "OVERLOADED",
  "retryable": true,
  "retryAfter": 5
}

Token 使用与成本控制​

什么是 Token？​

Token 是 AI 模型处理文本的基本单位。一个 Token 可能是一个单词、一个字符或一个标点符号。Gemini API 的计费基于 Token 使用量。

Token 计算示例：

  • "Hello" = 1 Token
  • "Hello world" = 2 Tokens
  • "你好" = 2 Tokens（中文字符通常每个字符是一个 Token）

Token 使用统计​

系统会记录每次 API 调用的 Token 使用情况：

interface TokenUsage {
  promptTokenCount?: number;      // 输入 Token 数（Prompt）
  candidatesTokenCount?: number;  // 输出 Token 数（AI 生成的内容）
  totalTokenCount?: number;       // 总 Token 数
}

成本优化策略​

1. Prompt 优化​

  • 精简 Prompt：移除不必要的说明和示例
  • 结构化数据：使用 JSON 格式传递数据，而不是自然语言描述
  • 分批处理：将大量数据分批处理，避免单次请求过大

2. 输出控制​

  • 限制输出长度：使用 maxTokens 参数限制输出长度
  • 指定输出格式：使用 responseMimeType: "application/json" 确保输出格式正确，减少无效输出

3. 缓存机制​

  • 结果缓存：对于相同输入的分析请求，可以缓存结果，避免重复调用
  • 模板缓存：Prompt 模板可以缓存，避免重复构建

Token 使用监控​

系统会在日志中记录 Token 使用情况，便于监控和成本分析：

{
  "timestamp": "2025-01-XXT12:00:00.000Z",
  "severity": "INFO",
  "message": "Gemini API 调用成功",
  "tokenUsage": {
    "promptTokenCount": 1500,
    "candidatesTokenCount": 800,
    "totalTokenCount": 2300
  },
  "executionTime": 3500
}

图像生成集成​

Imagen 4.0 概述​

Imagen 4.0 是 Google 开发的图像生成模型，可以通过文本描述生成高质量的图像。在本项目中，Imagen 4.0 用于生成受众画像的场景示意图。

图像生成流程​

sequenceDiagram
    participant FE as 前端
    participant BE as 后端
    participant IA as Imagen 4.0 API

    FE->>BE: 1. 发送图像生成请求<br>(包含图像描述 Prompt)
    BE->>BE: 2. 构建图像生成配置
    BE->>IA: 3. 调用 Imagen 4.0 API<br>(带重试机制)
    IA-->>BE: 4. 返回 Base64 编码的图像
    BE->>BE: 5. 验证和优化图像
    BE-->>FE: 6. 返回图像数据
    FE->>FE: 7. 显示图像到页面

图像生成配置​

请求参数：

{
  model: "imagen-4.0";
  prompt: string;              // 图像描述，如 "A modern gaming setup with RGB lighting..."
  aspectRatio?: "1:1";         // 宽高比，1:1 表示正方形
  personGeneration?: "DONT_ALLOW"; // 人物生成模式
}

图像描述 Prompt 设计：

图像描述 Prompt 应该：

  1. 具体明确：描述场景的具体细节（颜色、风格、元素等）
  2. 符合业务需求：生成的图像应该符合受众画像的特征
  3. 避免敏感内容：不使用可能触发内容审核的描述

示例：

Generate a professional, modern scene illustration showing:
- A young professional (age 25-34) in a casual business setting
- Modern technology devices (laptop, smartphone) visible
- Clean, minimalist design style
- Warm, inviting color palette (blues and whites)
- Professional atmosphere suitable for business presentation
- 1:1 aspect ratio, 250px x 250px resolution

图像生成错误处理​

图像生成可能因为以下原因失败：

  • 内容审核：描述内容触发审核机制
  • 服务过载：API 服务暂时不可用
  • 超时：生成时间过长（默认超时 120 秒）

系统会：

  1. 自动重试：对于可重试的错误，自动重试（最多 3 次）
  2. 使用占位符：如果生成失败，使用占位符图像
  3. 记录错误：记录详细的错误日志，便于问题诊断

总结​

本章节详细介绍了 Gemini AI 在本项目中的集成方式，包括：

  1. API 调用架构：前后端分离设计，统一的后端 API 管理
  2. Prompt Engineering：如何设计和优化 Prompt 以获得最佳输出
  3. 重试机制：指数退避策略和错误分类处理
  4. Token 使用：成本控制和监控机制
  5. 图像生成：Imagen 4.0 集成和图像生成流程

这些技术实现确保了系统能够稳定、高效地使用 Gemini AI 生成高质量的分析内容。

相关文档：