Gemini API Delphi 客户端

2026年4月14日 · 组件

Google Gemini 是目前最强大的多模态 AI 模型系列之一，擅长文本生成、图像理解、结构化输出和函数调用，适用于广泛的应用场景。对于希望在应用中集成 Gemini 的 Delphi 开发者，sgcWebSockets 提供 TsgcHTTP_API_Gemini——一个封装了完整 Google Gemini API 接口的综合性原生组件。

无论您是在构建对话式助手、生成结构化数据、处理图像、为语义搜索创建嵌入，还是编排工具增强型工作流，此组件都能让您通过简洁、类型安全的 Delphi 代码直接访问每项 Gemini 功能。无需 REST 样板代码，无需手动处理 JSON，只需放置组件、设置 API 密钥，即可开始构建。

完整 API 覆盖

Google Gemini API 的每项主要功能均开箱即用。

内容生成根据提示生成文本，支持可选的系统指令。通过温度、top-p、top-k 和停止序列微调输出。	实时流式传输通过 Server-Sent Events 逐词元流式传输响应，构建能在生成过程中实时显示答案的响应式 UI。	视觉理解将 base64 编码的图像数据与文本提示一起发送，Gemini 对视觉内容进行描述、解读和推理。
结构化 JSON 输出强制 Gemini 返回符合您的 schema 的有效 JSON，设置响应 MIME 类型和 schema 以保证可解析的结果。	函数调用使用 JSON Schema 定义自定义函数，Gemini 决定何时调用它们，支持构建智能体式的多步工作流。	向量嵌入为文本生成向量嵌入，驱动语义搜索、聚类、分类和推荐系统。
词元计数在发送请求前统计词元数，精确估算费用并管理上下文窗口预算。	模型管理列出所有可用 Gemini 模型或获取特定模型的详情，包括输入/输出词元限制。	内置重试与日志可配置重试次数和等待间隔，在瞬态故障时自动重试。提供完整请求/响应日志以便调试。

快速开始

在不到一分钟内将 Google Gemini 集成到您的 Delphi 项目中。放置组件、配置 API 密钥，发送第一条消息。

// Create the component and configure the API key
var
  Gemini: TsgcHTTP_API_Gemini;
  vResponse: string;
begin
  Gemini := TsgcHTTP_API_Gemini.Create(nil);
  Try
    Gemini.GeminiOptions.ApiKey := 'YOUR_API_KEY';
    // Send a simple message to Gemini
    vResponse := Gemini._CreateContent(
      'gemini-2.5-flash', 'Hello, Gemini!');
    ShowMessage(vResponse);
  Finally
    Gemini.Free;
  End;
end;

两种 API 风格。每项功能均提供便捷方法（基于字符串，代码最少）和类型化请求/响应类（完全控制，类型安全）两种方式，可根据需要选择。

内容生成与流式传输

GenerateContent API 是每次 Gemini 交互的基础。发送文本（可附加系统指令），以同步或实时流式方式接收响应。

系统指令

通过提供设置对话上下文、人格或约束条件的系统指令来控制 Gemini 的行为。

vResponse := Gemini._CreateContentWithSystem(
  'gemini-2.5-flash',
  'You are a helpful assistant that responds in Spanish.',
  'What is the capital of France?');
// Returns: "La capital de Francia es París."

实时流式传输

对于响应式用户界面，通过 Server-Sent Events 逐词元流式传输 Gemini 的响应。分配 OnHTTPAPISSE 事件处理程序并调用 _CreateContentStream。

// Enable streaming via SSE
Gemini.OnHTTPAPISSE := OnSSEEvent;
Gemini._CreateContentStream('gemini-2.5-flash',
  'Tell me a story about a brave explorer.');
procedure TForm1.OnSSEEvent(Sender: TObject;
  const aEvent, aData: string; var Cancel: Boolean);
begin
  // aData: JSON payload with generated content
  Memo1.Lines.Add(aData);
end;

高级类型化 API

若需完全控制请求参数（温度、top-p、top-k、停止序列、最大输出词元数），请使用类型化请求和响应类。

var
  oRequest: TsgcGeminiClass_Request_GenerateContent;
  oResponse: TsgcGeminiClass_Response_GenerateContent;
begin
  oRequest := TsgcGeminiClass_Request_GenerateContent.Create;
  Try
    oRequest.Model := 'gemini-2.5-flash';
    oRequest.SystemInstruction := 'You are a helpful assistant.';
    oRequest.MaxOutputTokens := 2048;
    oRequest.Temperature := 0.7;
    oRequest.TopP := 0.9;
    oRequest.TopK := 40;
    oRequest.Contents.Add('user', 'Explain quantum computing in simple terms.');
    oResponse := Gemini.CreateContent(oRequest);
    Try
      if Length(oResponse.Candidates) > 0 then
        ShowMessage(oResponse.Candidates[0].Parts[0].Text);
    Finally
      oResponse.Free;
    End;
  Finally
    oRequest.Free;
  End;
end;

视觉——图像理解

Gemini 原生支持多模态。将照片、截图、图表或图形与文本提示一起发送，获取详细描述、数据提取或视觉问答。

// Load an image and ask Gemini to describe it
var
  vBase64: string;
begin
  vBase64 := sgcBase64Encode(LoadFileToBytes('product-photo.png'));
  ShowMessage(Gemini._CreateVisionContent(
    'gemini-2.5-flash',
    'Describe this product image for an e-commerce listing.',
    vBase64, 'image/png'));
end;

使用场景。自动化质量检测、为无障碍访问生成替代文本、从图表中提取数据，或构建视觉搜索功能——全部通过原生 Delphi 代码实现。

结构化 JSON 输出

保证 Gemini 返回符合您确切 schema 的有效、可解析 JSON。设置响应 MIME 类型和 schema 以消除后处理步骤——响应可直接反序列化到您的 Delphi 记录中。

var
  vSchema, vResponse: string;
begin
  vSchema :=
    '{"type":"object","properties":{"name":{"type":"string"},' +
    '"age":{"type":"integer"}},"required":["name","age"]}';
  vResponse := Gemini._CreateContentJSON(
    'gemini-2.5-flash',
    'Extract the name and age: John is 30 years old.',
    vSchema);
  // Returns: {"name": "John", "age": 30}
end;

schema 强制执行。通过将 ResponseMimeType 设置为 'application/json' 并提供 ResponseSchema，Gemini 每次都保证输出结构有效。

函数调用

使用 JSON Schema 定义自定义函数，Gemini 将决定何时以何种方式调用它们。这是构建将 AI 与您的业务逻辑连接起来的智能体式多步工作流的基础。

var
  oRequest: TsgcGeminiClass_Request_GenerateContent;
  oFunc: TsgcGeminiClass_Request_FunctionDeclaration;
  oResponse: TsgcGeminiClass_Response_GenerateContent;
begin
  oRequest := TsgcGeminiClass_Request_GenerateContent.Create;
  Try
    oRequest.Model := 'gemini-2.5-flash';
    // Define a function
    oFunc := TsgcGeminiClass_Request_FunctionDeclaration.Create;
    oFunc.Name := 'get_weather';
    oFunc.Description := 'Get the current weather in a location';
    oFunc.Parameters :=
      '{"type":"object","properties":{"location":{"type":"string"}}}';
    oRequest.FunctionDeclarations.Add(oFunc);
    oRequest.Contents.Add('user',
      'What is the weather in Madrid?');
    oResponse := Gemini.CreateContent(oRequest);
    Try
      // Check if Gemini wants to call a function
      if oResponse.Candidates[0].Parts[0].FunctionCallName  '' then
      begin
        ShowMessage('Function: ' + oResponse.Candidates[0].Parts[0].FunctionCallName);
        ShowMessage('Args: ' + oResponse.Candidates[0].Parts[0].FunctionCallArgs);
      end;
    Finally
      oResponse.Free;
    End;
  Finally
    oRequest.Free;
  End;
end;

向量嵌入

为文本生成高质量向量嵌入，驱动语义搜索、文档聚类、推荐引擎和分类任务。

// Generate embeddings for a text
var
  vEmbedding: string;
begin
  vEmbedding := Gemini._EmbedContent(
    'text-embedding-004',
    'Delphi is a powerful programming language.');
  ShowMessage(vEmbedding);
end;

如需完全控制，使用类型化 API 访问原始嵌入值数组。

var
  oResponse: TsgcGeminiClass_Response_Embedding;
  i: Integer;
begin
  oResponse := Gemini.EmbedContent(
    'text-embedding-004',
    'Delphi is a powerful programming language.');
  Try
    for i := 0 to Length(oResponse.Values) - 1 do
      Memo1.Lines.Add(FloatToStr(oResponse.Values[i]));
  Finally
    oResponse.Free;
  End;
end;

词元计数

在发送请求前精确估算费用并管理上下文窗口预算。

var
  vTokens: string;
begin
  vTokens := Gemini._CountTokens(
    'gemini-2.5-flash',
    'How many tokens does this message consume?');
  ShowMessage(vTokens);
end;

模型管理

以编程方式查询可用 Gemini 模型。列出所有模型或获取特定模型 ID 的详情，包括显示名称、描述和词元限制。

// List all available Gemini models
vModels := Gemini._GetModels;
// Get details for a specific model
vModel := Gemini._GetModel('gemini-2.5-flash');
// Typed API: access model properties directly
var
  oModel: TsgcGeminiClass_Response_Model;
begin
  oModel := Gemini.GetModel('gemini-2.5-flash');
  Try
    ShowMessage('Name: ' + oModel.DisplayName);
    ShowMessage('Input limit: ' + IntToStr(oModel.InputTokenLimit));
    ShowMessage('Output limit: ' + IntToStr(oModel.OutputTokenLimit));
  Finally
    oModel.Free;
  End;
end;

配置与选项

通过全面的配置选项微调组件行为。

属性	说明
`GeminiOptions.ApiKey`	您的 Google Gemini API 密钥（必填）
`HttpOptions.ReadTimeout`	HTTP 读取超时（毫秒，默认：60000）
`LogOptions.Enabled`	启用请求/响应日志记录
`LogOptions.FileName`	请求/响应捕获的日志文件路径
`RetryOptions.Enabled`	在瞬态故障（429、503）时自动重试
`RetryOptions.Retries`	最大重试次数（默认：3）
`RetryOptions.Wait`	重试间等待时间（毫秒，默认：3000）

请求参数

参数	说明
`Temperature`	采样温度（0.0～2.0），值越低输出越确定。
`TopP`	核采样（0.0～1.0），控制累积概率截止值。
`TopK`	Top-K 采样，将词元选择限制在概率最高的 K 个候选项中。
`MaxOutputTokens`	响应中的最大词元数（默认：4096）。
`StopSequences`	遇到时停止生成的自定义序列。
`ResponseMimeType`	输出格式：JSON 使用 'application/json'，纯文本使用 'text/plain'。
`ToolChoice`	控制模型选择要调用的函数的方式。