从协议规范到C++封装：Gemini 大模型接入 SDK 的完整路径

1 ~> Gemini API 体系概述

1.1 两套 API 设计机制与选型

1.1.1 设计背景

• OpenAI 兼容 API ：厂商用来降低开发者迁移成本的获客手段，能让现有的 OpenAI 技术栈零成本切换；但长期依赖会形成品牌替代效应，难以建立自己的技术护城河。
• 原生 API（models.generateContent） ：充分释放 Gemini 多模态、函数调用、代码执行等原生能力，适配垂直场景深度定制，是厂商实现技术自主、构建生态护城河的核心方案。
• 行业演进规律：大模型厂商普遍遵循「追随者→挑战者→引领者」的 API 演进路径，兼容期快速获客，成熟期推出原生标准。

1.1.2 接入选型策略

• 快速迁移 / 兼容现有 OpenAI 代码：采用 OpenAI 兼容 API，仅需修改密钥、Base URL、模型名三处核心配置。
• 深度使用 Gemini 原生能力：采用 Google 原生 API，发挥多模态、长上下文、工具调用等特性。
• 本工程接入方案：先用 OpenAI 兼容 API 完成基础对话能力接入，同时为原生 API 预留扩展空间。

1.2 Gemini Flash 模型核心特性

• 模型标识：gemini-2.0-flash
• 核心定位：低延迟、高吞吐的急速响应大语言模型
• 适用场景：实时对话交互、快速内容生成等对响应时效要求高的场景
• 能力矩阵：文本生成、多模态理解、嵌入表示、长上下文、代码执行、JSON 模式、函数调用、系统指令

---

2 ~> Gemini Provider 类架构设计

2.1 类继承体系

• 抽象基类：LLMProvider，定义大模型提供者统一接口规范，实现多态调用
• 具体实现类：GeminiProvider，封装 Gemini API 的请求构造、响应解析、流式处理逻辑
• 统一接口契约：
  • 模型初始化：initModel
  • 可用性检测：isAvailable
  • 模型元信息获取：getModelName / getModelDesc
  • 流式消息接口：sendMessageStream，支持增量数据回调

2.2 头文件定义（GeminiProvider.h）

#ifndef GEMINI_PROVIDER_H
#define GEMINI_PROVIDER_H

#include "LLMProvider.h"
#include <string>
#include <map>
#include <functional>
#include <vector>

namespace ai_chat_sdk {

class GeminiProvider : public LLMProvider {
public:

    virtual bool initModel(const std::map<std::string, std::string>& modelConfig) override;

    virtual bool isAvailable() const override;

    virtual std::string getModelName() const override;

    virtual std::string getModelDesc() const override;

    virtual std::string sendMessageStream(
        const std::vector<std::string>& messages,
        std::function<void(const std::string&, bool)> callback) override;

protected:
    bool _isAvailable = false;       
    std::string _apiKey;             
    std::string _endpoint;           
};

}

#endif

2.3 源文件核心实现（GeminiProvider.cpp）

2.3.1 模型初始化函数

功能：从配置映射中读取核心参数，完成合法性校验与状态初始化。

#include "../include/GeminiProvider.h"
#include "../include/util/myLog.h"

namespace ai_chat_sdk {

bool GeminiProvider::initModel(const std::map<std::string, std::string>& modelConfig) {

    auto it = modelConfig.find("api_key");
    if (it == modelConfig.end()) {
        ERR("GeminiProvider::initModel: api_key not found in modelConfig");
        return false;
    }
    _apiKey = it->second;

    it = modelConfig.find("endpoint");
    if (it == modelConfig.end()) {
        ERR("GeminiProvider::initModel: endpoint not found in modelConfig");
        return false;
    }
    _endpoint = it->second;

    _isAvailable = true;
    INFO("GeminiProvider::initModel: init model success, endpoint:{}", _endpoint);
    return true;
}

安全规范：日志输出禁止打印 API 密钥明文，仅输出端点地址，避免密钥泄露风险。

2.3.2 可用性检测

bool GeminiProvider::isAvailable() const {
return _isAvailable;
}


2.3.3 模型元信息获取

std::string GeminiProvider::getModelName() const {
    return "gemini-2.0-flash";
}

std::string GeminiProvider::getModelDesc() const {
    return "Google的急速响应模型，专为大模型部署和快速交互的场景设计";
}

---

3 ~> OpenAI 兼容 API 协议规范

3.1 接口端点

• 请求方法：POST
• 基准 URL：`
• 接口路径：/v1beta/openai/chat/completions
• 完整请求地址：`

3.2 请求头规范

参数名	类型	取值规范
Content-Type	string	固定值 application/json
Authorization	string	格式为 Bearer {GEMINI_API_KEY}

3.3 请求体核心参数

参数名	类型	说明
model	string	模型标识，如 gemini-2.0-flash
messages	array	对话消息列表，每条包含role与content字段
temperature	float	采样温度，控制输出随机性，典型值 0.7
max_tokens	integer	最大生成 Token 数限制
stream	boolean	是否开启流式响应，true 为增量返回，false 为全量返回

请求体示例：

{
"model": "gemini-2.0-flash",
"messages": [
{
"role": "user",
"content": "你是谁?"
}
],
"temperature": 0.7,
"max_tokens": 2048,
"stream": false
}


3.4 全量响应数据结构

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "我是一个大型语言模型，由Google训练",
                "role": "assistant"
            }
        }
    ],
    "created": 1759981735,
    "id": "pzDnaOXSPjz7IP_tG-6Ao",
    "model": "gemini-2.0-flash",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 12,
        "prompt_tokens": 3,
        "total_tokens": 15
    }
}

• 关键字段说明：
  • finish_reason：生成终止原因，stop表示正常结束
  • usage：Token 消耗统计，包含提示 Token、补全 Token 与总 Token

---

4 ~> 工程接入与测试实践

4.1 项目目录结构

sdk/
├── include/
│   ├── common.h              
│   ├── LLMProvider.h         
│   ├── ChatGPTProvider.h     
│   ├── DeepSeekProvider.h    
│   ├── GeminiProvider.h      
│   └── util/
│       └── myLog.h           
├── src/
│   ├── ChatGPTProvider.cpp
│   ├── DeepSeekProvider.cpp
│   ├── GeminiProvider.cpp    
│   └── util/
│       └── myLog.cpp         
└── test/
    ├── build/                
    ├── CMakeLists.txt        
    └── testLLM.cpp

4.2 Apifox 接口测试配置

4.2.1 环境管理

• 全局前置 URL：`
• 环境变量体系：
  • GEMINI_API_KEY：密钥类变量，加密存储
  • 支持多环境隔离：开发环境、测试环境、正式环境、本地 Mock

4.2.2 接口测试流程

1. 新建 POST 请求，填写完整接口路径
2. Headers 中配置Content-Type与Authorization
3. Body 选择 JSON 格式，填入请求体参数
4. 配置网络代理，确保 Google API 可达
5. 发送请求，校验响应状态码与数据结构

4.3 网络与代理配置

• 前置条件：Gemini API 服务需通过代理网络方可访问
• 代理配置规则：
  • 接口请求代理：仅作用于 API 请求，不影响 Apifox 平台连接
  • 自定义代理：配置代理 IP 与端口（示例：127.0.0.1:7890）
  • 代理绕过列表：配置无需代理的地址，以英文逗号分隔

---

结尾

uu们，本文的内容到这里就全部结束了，艾莉丝在这里再次感谢您的阅读！