---

Laravel 的 Gemini PHP 是一个社区维护的 PHP API 客户端，允许你与 Gemini AI API 进行交互。

• Fatih AYDIN github.com/aydinfatih
• Vytautas Smilingis github.com/Plytas

更多信息请查看 google-gemini-php/client 仓库。

目录

• 先决条件
• 设置
  • 安装
  • 设置你的 API 密钥
  • 升级到 2.0
• 使用方法
  • 聊天资源（Chat Resource）
    • 纯文本输入
    • 文本和图像输入
    • 文本和视频输入
    • 图像生成
    • 多轮对话（Chat）
    • 带流式传输的聊天
    • 流式生成内容
    • 结构化输出
    • 函数调用（Function calling）
    • 代码执行（Code Execution）
    • 使用 Google 搜索进行事实核查（Grounding with Google Search）
    • 系统指令（System Instructions）
    • 语音生成（Speech generation）
    • 思考模式（Thinking Mode）
    • 计算 token 数量
    • 配置
  • 文件管理（File Management）
    • 文件上传
    • 列出文件
    • 获取文件元数据
    • 删除文件
  • 缓存内容（Cached Content）
    • 创建缓存内容
    • 列出缓存内容
    • 获取缓存内容
    • 更新缓存内容
    • 删除缓存内容
    • 使用缓存内容
  • 嵌入资源（Embedding Resource）
  • 模型（Models）
    • 列出模型
    • 获取模型
• 故障排除
• 测试

先决条件

要完成本快速入门，请确保你的开发环境满足以下要求：

• 需要 PHP 8.1+
• 需要 Laravel 9,10,11,12

设置

安装

首先，通过 Composer 包管理器安装 Gemini：

composer require google-gemini-php/laravel

接下来，执行安装命令：

php artisan gemini:install

这将在你的项目中创建一个 config/gemini.php 配置文件，你可以使用环境变量根据需要进行修改。.env 文件中已经自动添加了空白的 Gemini API 密钥环境变量。

GEMINI_API_KEY=

你也可以定义以下环境变量。

GEMINI_BASE_URL=
GEMINI_REQUEST_TIMEOUT=

设置你的 API 密钥

要使用 Gemini API，你需要一个 API 密钥。如果你还没有密钥，请在 Google AI Studio 中创建一个。

获取 API 密钥

升级到 2.0

从 2.0 版本开始，此包仅支持 Gemini v1beta API（参见 API 版本）。

要更新，请运行以下命令：

composer require google-gemini-php/laravel:^2.0

此版本引入了对以下新功能的支持：

• 结构化输出（Structured output）
• 系统指令（System instructions）
• 文件上传（File uploads）
• 函数调用（Function calling）
• 代码执行（Code execution）
• 使用 Google 搜索进行事实核查（Grounding with Google Search）
• 缓存内容（Cached content）
• 思考模式配置（Thinking model configuration）
• 语音模式配置（Speech model configuration）

\Gemini\Enums\ModelType 枚举已被弃用，并将在下一个主要版本中移除。同时，Gemini::geminiPro() 和 Gemini::geminiFlash() 方法也已被移除。 我们建议使用 Gemini::generativeModel() 方法并直接传入模型字符串。所有之前接受 ModelType 枚举的方法现在都接受 BackedEnum。我们建议你为方便起见实现自己的枚举。

此处可能未列出其他破坏性变更。如果你遇到任何问题，请提交 issue 或 pull request。

使用方法

与 Gemini API 交互：

use Gemini\Enums\ModelVariation;
use Gemini\GeminiHelper;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');

$result->text(); // Hello! How can I assist you today?

// 辅助方法用法
$result = Gemini::generativeModel(
    model: GeminiHelper::generateGeminiModel(
        variation: ModelVariation::FLASH,
        generation: 2.5,
        version: "preview-04-17"
    ), // models/gemini-2.5-flash-preview-04-17
)->generateContent('Hello');

$result->text(); // Hello! How can I assist you today?

聊天资源（Chat Resource）

有关 Gemini API v1 支持的完整输入格式和方法列表，请参阅 模型文档。

纯文本输入

根据输入消息从模型生成响应。

use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')->generateContent('Hello');

$result->text(); // Hello! How can I assist you today?

文本和图像输入

通过向 Gemini 模型提供文本提示和图像来生成响应。

use Gemini\Data\Blob;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->generateContent([
        'What is this picture?',
        new Blob(
            mimeType: MimeType::IMAGE_JPEG,
            data: base64_encode(
                file_get_contents('https://storage.googleapis.com/generativeai-downloads/images/scones.jpg')
            )
        )
    ]);

$result->text(); //  The picture shows a table with a white tablecloth. On the table are two cups of coffee, a bowl of blueberries, a silver spoon, and some flowers. There are also some blueberry scones on the table.

文本和视频输入

使用上传的视频文件通过 Gemini API 处理视频内容并获取 AI 生成的描述。

use Gemini\Data\UploadedFile;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash') ->generateContent([ 'What is this video?', new UploadedFile( fileUri: '123-456', // accepts just the name or the full URI mimeType: MimeType::VIDEO_MP4 ) ]);

$result->text(); // The video shows...

#### 图像生成（Image Generation）
使用 Imagen 模型根据文本提示生成图像。

```php
use Gemini\Data\ImageConfig;
use Gemini\Data\GenerationConfig;
use Gemini\Laravel\Facades\Gemini;

$imageConfig = new ImageConfig(aspectRatio: '16:9');
$generationConfig = new GenerationConfig(imageConfig: $imageConfig);

$response = Gemini::generativeModel(model: 'gemini-2.5-flash-image')
    ->withGenerationConfig($generationConfig)
    ->generateContent('Draw a futuristic city');

// Save the image
file_put_contents('image.png', base64_decode($response->parts()[0]->inlineData->data));

多轮对话（Multi-turn Conversations，Chat）

使用 Gemini，你可以构建跨越多轮的自由形式对话。

use Gemini\Data\Content;
use Gemini\Enums\Role;
use Gemini\Laravel\Facades\Gemini;

$chat = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->startChat(history: [
        Content::parse(part: 'The stories you write about what I have to say should be one line. Is that clear?'),
        Content::parse(part: 'Yes, I understand. The stories I write about your input should be one line long.', role: Role::MODEL)
    ]);

$response = $chat->sendMessage('Create a story set in a quiet village in 1600s France');
echo $response->text(); // Amidst rolling hills and winding cobblestone streets, the tranquil village of Beausoleil whispered tales of love, intrigue, and the magic of everyday life in 17th century France.

$response = $chat->sendMessage('Rewrite the same story in 1600s England');
echo $response->text(); // In the heart of England's lush countryside, amidst emerald fields and thatched-roof cottages, the village of Willowbrook unfolded a tapestry of love, mystery, and the enchantment of ordinary days in the 17th century.

带流式传输的聊天（Chat with Streaming）

你也可以在聊天会话中以流式方式接收响应。流式传输完成后，历史记录会自动更新为完整的响应内容。

use Gemini\Laravel\Facades\Gemini;

$chat = Gemini::generativeModel(model: 'gemini-2.0-flash')->startChat();

$stream = $chat->streamSendMessage('Hello');

foreach ($stream as $response) {
    echo $response->text();
}

流式生成内容（Stream Generate Content）

默认情况下，模型会在完成整个生成过程后返回响应。为了实现更快的交互，你可以不等待完整结果，而是使用流式传输来处理部分结果。

use Gemini\Laravel\Facades\Gemini;

$stream = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->streamGenerateContent('Write long a story about a magic backpack.');

foreach ($stream as $response) {
    echo $response->text();
}

结构化输出（Structured Output）

Gemini 默认生成非结构化文本，但某些应用需要结构化文本。针对这些场景，你可以约束 Gemini 以 JSON 格式（一种适合自动化处理的结构化数据格式）进行响应。你还可以约束模型仅从枚举（enum）中指定的选项中选择响应。

use Gemini\Data\GenerationConfig;
use Gemini\Data\Schema;
use Gemini\Enums\DataType;
use Gemini\Enums\ResponseMimeType;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withGenerationConfig(
        generationConfig: new GenerationConfig(
            responseMimeType: ResponseMimeType::APPLICATION_JSON,
            responseSchema: new Schema(
                type: DataType::ARRAY,
                items: new Schema(
                    type: DataType::OBJECT,
                    properties: [
                        'recipe_name' => new Schema(type: DataType::STRING),
                        'cooking_time_in_minutes' => new Schema(type: DataType::INTEGER)
                    ],
                    required: ['recipe_name', 'cooking_time_in_minutes'],
                )
            )
        )
    )
    ->generateContent('List 5 popular cookie recipes with cooking time');

$result->json();

//[
//    {
//      +"cooking_time_in_minutes": 10,
//      +"recipe_name": "Chocolate Chip Cookies",
//    },
//    {
//      +"cooking_time_in_minutes": 12,
//      +"recipe_name": "Oatmeal Raisin Cookies",
//    },
//    {
//      +"cooking_time_in_minutes": 10,
//      +"recipe_name": "Peanut Butter Cookies",
//    },
//    {
//      +"cooking_time_in_minutes": 10,
//      +"recipe_name": "Snickerdoodles",
//    },
//    {
//      +"cooking_time_in_minutes": 12,
//      +"recipe_name": "Sugar Cookies",
//    },
//  ]

函数调用（Function calling）

Gemini 支持定义和使用自定义函数，模型可以在对话过程中调用这些函数。这使得模型能够通过你定义的函数执行特定操作或计算。

<?php

use Gemini\Data\Content;
use Gemini\Data\FunctionCall;
use Gemini\Data\FunctionDeclaration;
use Gemini\Data\FunctionResponse;
use Gemini\Data\Part;
use Gemini\Data\Schema;
use Gemini\Data\Tool;
use Gemini\Enums\DataType;
use Gemini\Enums\Role;
use Gemini\Laravel\Facades\Gemini;

function handleFunctionCall(FunctionCall $functionCall): Content
{
    if ($functionCall->name === 'addition') {
        return new Content(
            parts: [
                new Part(
                    functionResponse: new FunctionResponse(
                        name: 'addition',
                        response: ['answer' => $functionCall->args['number1'] + $functionCall->args['number2']],
                    ),
                    thoughtSignature: 'some-signature' // 可选：某些模型（例如 Gemini 3 Pro）需要此参数
                )
            ],
            role: Role::USER
        );
    }

    //Handle other function calls
}

$chat = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withTool(new Tool(
        functionDeclarations: [
            new FunctionDeclaration(
                name: 'addition',
                description: 'Performs addition',
                parameters: new Schema(
                    type: DataType::OBJECT,
                    properties: [
                        'number1' => new Schema(
                            type: DataType::NUMBER,
                            description: 'First number'
                        ),
                        'number2' => new Schema(
                            type: DataType::NUMBER,
                            description: 'Second number'
                        ),
                    ],
                    required: ['number1', 'number2']
                )
            )
        ]
    ))
    ->startChat();

$response = $chat->sendMessage('What is 4 + 3?');

if ($response->parts()[0]->functionCall !== null) { $thoughtSignature = $response->parts()[0]->thoughtSignature; // 访问思维签名（thought signature） $functionResponse = handleFunctionCall($response->parts()[0]->functionCall);

$response = $chat->sendMessage($functionResponse);

}

echo $response->text(); // 4 + 3 = 7

#### 代码执行（Code Execution）
Gemini 模型可以自动生成并执行代码，并将结果返回给你。这对于需要计算、数据处理或其他编程操作的任务非常有用。

```php
use Gemini\Data\CodeExecution;
use Gemini\Data\Tool;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withTool(new Tool(codeExecution: CodeExecution::from()))
    ->generateContent('前 50 个质数的和是多少？请生成并运行代码进行计算，并确保包含全部 50 个质数。');

// 访问已执行的代码和结果
foreach ($response->parts() as $part) {
    if ($part->executableCode !== null) {
        echo "Language: " . $part->executableCode->language->value . "\n";
        echo "Code: " . $part->executableCode->code . "\n";
    }
    if ($part->codeExecutionResult !== null) {
        echo "Outcome: " . $part->codeExecutionResult->outcome->value . "\n";
        echo "Output: " . $part->codeExecutionResult->output . "\n";
    }
}

使用 Google 搜索进行事实核查（Grounding with Google Search）

使用 Google 搜索进行事实核查可将 Gemini 模型连接到实时网络内容，并支持所有可用语言。这使得 Gemini 能够提供更准确的答案，并引用超出其知识截止日期的可验证来源。

适用于 Gemini 2.0 及更高版本模型（推荐）：

使用简单的 GoogleSearch 工具，它会自动处理搜索查询：

use Gemini\Data\GoogleSearch;
use Gemini\Data\Tool;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withTool(new Tool(googleSearch: GoogleSearch::from()))
    ->generateContent('谁赢得了 2024 年欧洲杯？');

echo $response->text();
// 西班牙赢得了 2024 年欧洲杯，在决赛中以 2-1 击败英格兰。

// 访问事实核查元数据以查看来源
$groundingMetadata = $response->candidates[0]->groundingMetadata;

if ($groundingMetadata !== null) {
    // 获取已执行的搜索查询
    foreach ($groundingMetadata->webSearchQueries ?? [] as $query) {
        echo "Search query: {$query}\n";
    }
    
    // 获取网络来源
    foreach ($groundingMetadata->groundingChunks ?? [] as $chunk) {
        if ($chunk->web !== null) {
            echo "Source: {$chunk->web->title} - {$chunk->web->uri}\n";
        }
    }
    
    // 获取事实核查支持信息（将文本片段与来源关联）
    foreach ($groundingMetadata->groundingSupports ?? [] as $support) {
        if ($support->segment !== null) {
            echo "Text segment: {$support->segment->text}\n";
            echo "Supported by chunks: " . implode(', ', $support->groundingChunkIndices ?? []) . "\n";
        }
    }
}

系统指令（System Instructions）

系统指令允许你根据特定需求和使用场景引导模型的行为。你可以设定模型的角色和个性、定义响应格式，并为模型行为提供目标和约束。

use Gemini\Data\Content;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withSystemInstruction(
        Content::parse('你是一个乐于助人的助手，总是以海盗的风格回答问题。在所有回答中使用航海术语和海盗俚语。')
    )
    ->generateContent('给我讲讲 PHP 编程');

echo $response->text();
// 啊哈，伙计！让俺给你讲讲这个叫 PHP 编程的宝贝儿……

你也可以将系统指令与其他功能结合使用：

use Gemini\Data\Content;
use Gemini\Data\GenerationConfig;
use Gemini\Enums\ResponseMimeType;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withSystemInstruction(
        Content::parse('你是一个 JSON API。始终以有效的 JSON 对象进行响应。保持简洁。')
    )
    ->withGenerationConfig(
        new GenerationConfig(responseMimeType: ResponseMimeType::APPLICATION_JSON)
    )
    ->generateContent('给我一些关于埃菲尔铁塔的信息');

print_r($response->json());

语音生成（Speech generation）

Gemini 支持从文本生成语音。要使用此功能，请确保使用支持该功能的模型。模型将输出 base64 编码的音频字符串。

单说话人

use Gemini\Data\GenerationConfig;
use Gemini\Data\SpeechConfig;
use Gemini\Data\VoiceConfig;
use Gemini\Data\PrebuiltVoiceConfig;
use Gemini\Enums\ResponseModality;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel('gemini-2.5-flash-preview-tts')->withGenerationConfig(
    generationConfig: new GenerationConfig(
        responseModalities: [ResponseModality::AUDIO],
        speechConfig: new SpeechConfig(
            voiceConfig: new VoiceConfig(
                new PrebuiltVoiceConfig(voiceName: 'Kore')
            ),
        )
    )
)->generateContent("Say: Hello world");

// 响应包含 base64 编码的音频
$audioData = $response->parts()[0]->inlineData->data;

多说话人

use Gemini\Data\GenerationConfig;
use Gemini\Data\SpeechConfig;
use Gemini\Data\MultiSpeakerVoiceConfig;
use Gemini\Data\PrebuiltVoiceConfig;
use Gemini\Data\SpeakerVoiceConfig;
use Gemini\Data\VoiceConfig;
use Gemini\Enums\ResponseModality;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel('gemini-2.5-flash-preview-tts')->withGenerationConfig(
    generationConfig: new GenerationConfig(
        responseModalities: [ResponseModality::AUDIO],
        speechConfig: new SpeechConfig(
            multiSpeakerVoiceConfig: new MultiSpeakerVoiceConfig([
                new SpeakerVoiceConfig(
                    speaker: 'Joe',
                    voiceConfig: new VoiceConfig(
                        new PrebuiltVoiceConfig('Kore'),
                    )
                ),
                new SpeakerVoiceConfig(
                    speaker: 'Jane',
                    voiceConfig: new VoiceConfig(
                        new PrebuiltVoiceConfig('Puck'),
                    )
                )
            ]),
            languageCode: 'en-GB'
        )
    )
)->generateContent("TTS the following conversation between Joe and Jane:\nJoe: How's it going today Jane?\nJane: Not too bad, how about you?");

// 响应包含 base64 编码的音频
$audioData = $response->parts()[0]->inlineData->data;

思考模式（Thinking Mode）

对于支持思考模式的模型（如 Gemini 2.0），你可以配置模型以展示其推理过程。这在解决复杂问题以及理解模型如何得出答案时非常有用。

use Gemini\Data\GenerationConfig;
use Gemini\Data\ThinkingConfig;
use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash-thinking-exp')
    ->withGenerationConfig(
        new GenerationConfig(
            thinkingConfig: new ThinkingConfig(
                includeThoughts: true,
                thinkingBudget: 1024
            )
        )
    )
    ->generateContent('Solve this logic puzzle: If all Bloops are Razzies and all Razzies are Lazzies, are all Bloops definitely Lazzies?');

// 访问模型的思考过程和最终答案
foreach ($response->candidates[0]->content->parts as $part) {
    if ($part->thought === true) {
        // 此部分内容包含模型的思考过程
        echo "Model's thinking: " . $part->text . "\n\n";
    } else if ($part->text !== null) {
        // 这是最终答案
        echo "Final answer: " . $part->text . "\n";
    }
}

计算 Token 数量

当你使用较长的提示（prompt）时，在将内容发送给模型之前计算 token 数量可能会很有用。

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->countTokens('Write a story about a magic backpack.');

echo $response->totalTokens; // 9

配置

你发送给模型的每个提示都包含控制模型如何生成响应的参数值。对于不同的参数值，模型可能会生成不同的结果。了解更多关于 模型参数（model parameters） 的信息。

此外，你可以使用安全设置（safety settings）来调整收到可能被视为有害内容的响应的可能性。默认情况下，安全设置会阻止在所有维度上具有中等或高概率的不安全内容。了解更多关于 安全设置（safety settings） 的信息。

use Gemini\Data\GenerationConfig;
use Gemini\Enums\HarmBlockThreshold;
use Gemini\Data\SafetySetting;
use Gemini\Enums\HarmCategory;
use Gemini\Laravel\Facades\Gemini;

$safetySettingDangerousContent = new SafetySetting(
    category: HarmCategory::HARM_CATEGORY_DANGEROUS_CONTENT,
    threshold: HarmBlockThreshold::BLOCK_ONLY_HIGH
);

$safetySettingHateSpeech = new SafetySetting(
    category: HarmCategory::HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold::BLOCK_ONLY_HIGH
);

$generationConfig = new GenerationConfig(
    stopSequences: [
        'Title',
    ],
    maxOutputTokens: 800,
    temperature: 1,
    topP: 0.8,
    topK: 10
);

$generativeModel = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withSafetySetting($safetySettingDangerousContent)
    ->withSafetySetting($safetySettingHateSpeech)
    ->withGenerationConfig($generationConfig)
    ->generateContent("Write a story about a magic backpack.");

文件管理（File Management）

文件 API 允许你每个项目最多存储 20GB 的文件，单个文件最大为 2GB。文件将保存 48 小时，并可在 API 调用中访问。

文件上传

若要在各种提示中引用较大的文件和视频，请将它们上传到 Gemini 存储。

use Gemini\Enums\FileState;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$files = Gemini::files();
echo "Uploading\n";
$meta = $files->upload(
    filename: 'video.mp4',
    mimeType: MimeType::VIDEO_MP4,
    displayName: 'Video'
);
echo "Processing";
do {
    echo ".";
    sleep(2);
    $meta = $files->metadataGet($meta->uri);
} while (!$meta->state->complete());
echo "\n";

if ($meta->state == FileState::Failed) {
    die("Upload failed:\n" . json_encode($meta->toArray(), JSON_PRETTY_PRINT));
}

echo "Processing complete\n" . json_encode($meta->toArray(), JSON_PRETTY_PRINT);
echo "\n{$meta->uri}";

列出文件

列出项目中所有已上传的文件。

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::files()->list(pageSize: 10);

foreach ($response->files as $file) {
    echo "Name: {$file->name}\n";
    echo "Display Name: {$file->displayName}\n";
    echo "Size: {$file->sizeBytes} bytes\n";
    echo "MIME Type: {$file->mimeType}\n";
    echo "State: {$file->state->value}\n";
    echo "---\n";
}

// 如果有下一页，则获取下一页
if ($response->nextPageToken) {
    $nextPage = Gemini::files()->list(pageSize: 10, nextPageToken: $response->nextPageToken);
}

获取文件元数据

获取特定文件的元数据。

use Gemini\Laravel\Facades\Gemini;

$meta = Gemini::files()->metadataGet('abc123');

// 或使用完整 URI
$meta = Gemini::files()->metadataGet($file->uri);

echo "File: {$meta->displayName}\n";
echo "State: {$meta->state->value}\n";
echo "Size: {$meta->sizeBytes} bytes\n";

删除文件

从 Gemini 存储中删除文件。

use Gemini\Laravel\Facades\Gemini;

Gemini::files()->delete('files/abc123');

// 或使用完整 URI
Gemini::files()->delete($file->uri);

缓存内容（Cached Content）

上下文缓存（Context caching）允许你保存并重用预计算的输入 token，适用于频繁使用的共享内容。这可以降低具有大量共享上下文的请求的成本和延迟。

创建缓存内容

缓存将在多个请求中重复使用的内容。

use Gemini\Data\Content;
use Gemini\Laravel\Facades\Gemini;

$cachedContent = Gemini::cachedContents()->create(
    model: 'gemini-2.0-flash',
    systemInstruction: Content::parse('You are an expert PHP developer.'),
    parts: [
        'This is a large codebase...',
        'File 1 contents...',
        'File 2 contents...'
    ],
    ttl: '3600s', // 缓存 1 小时
    displayName: 'PHP Codebase Cache'
);

echo "Cached content created: {$cachedContent->name}\n";

列出缓存内容

列出项目中所有已缓存的内容。

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::cachedContents()->list(pageSize: 10);

foreach ($response->cachedContents as $cached) {
    echo "Name: {$cached->name}\n";
    echo "Display Name: {$cached->displayName}\n";
    echo "Model: {$cached->model}\n";
    echo "Expires: {$cached->expireTime}\n";
    echo "---\n";
}

获取缓存内容

通过名称检索特定的缓存内容。

use Gemini\Laravel\Facades\Gemini;

$cached = Gemini::cachedContents()->retrieve('cachedContents/abc123');

echo "Model: {$cached->model}\n";
echo "Created: {$cached->createTime}\n";
echo "Expires: {$cached->expireTime}\n";

更新缓存内容

更新缓存内容的过期时间。

use Gemini\Laravel\Facades\Gemini;

// 通过 TTL 延长
$updated = Gemini::cachedContents()->update(
    name: 'cachedContents/abc123',
    ttl: '7200s' // 延长 2 小时
);

// 或设置绝对过期时间
$updated = Gemini::cachedContents()->update(
    name: 'cachedContents/abc123',
    expireTime: '2024-12-31T23:59:59Z'
);

删除缓存内容

在不再需要时删除缓存内容。

use Gemini\Laravel\Facades\Gemini;

Gemini::cachedContents()->delete('cachedContents/abc123');

使用缓存内容

在请求中使用缓存内容以节省 token 并降低延迟。

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->withCachedContent('cachedContents/abc123')
    ->generateContent('Explain the main function in this codebase');

echo $response->text();

// 检查 token 使用情况
echo "Cached tokens used: {$response->usageMetadata->cachedContentTokenCount}\n";
echo "New tokens used: {$response->usageMetadata->promptTokenCount}\n";

嵌入资源（Embedding Resource）

嵌入（Embedding）是一种将信息表示为浮点数数组的技术。通过 Gemini，你可以将文本（单词、句子和文本块）转换为向量化形式，从而更方便地进行比较和对比。例如，主题或情感相似的两段文本应具有相近的嵌入向量，可通过余弦相似度（cosine similarity）等数学比较方法识别。

使用 text-embedding-004 模型，调用 embedContents 或 batchEmbedContents：

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::embeddingModel('text-embedding-004')
    ->embedContent("Write a story about a magic backpack.");

print_r($response->embedding->values);
//[
//    [0] => 0.008624583
//    [1] => -0.030451821
//    [2] => -0.042496547
//    [3] => -0.029230341
//    [4] => 0.05486475
//    [5] => 0.006694871
//    [6] => 0.004025645
//    [7] => -0.007294857
//    [8] => 0.0057651913
//    ...
//]

模型（Models）

建议查阅 Google 官方文档 获取最新支持的模型列表。

列出模型

通过编程方式查看可用的 Gemini 模型：

• pageSize（可选）：
  每页返回的最大模型数量。
  若未指定，默认每页返回 50 个模型。即使传入更大的值，该方法每页最多也只返回 1000 个模型。

• nextPageToken（可选）：
  从上一次 models.list 调用中获得的分页令牌。
  将前一次请求返回的 pageToken 作为参数传递给下一次请求，以获取下一页结果。
  分页时，除 pageToken 外，其他所有参数必须与提供该令牌的原始请求一致。

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::models()->list(pageSize: 3, nextPageToken: 'ChFtb2RlbHMvZ2VtaW5pLXBybw==');

$response->models;
//[
//    [0] => Gemini\Data\Model Object
//        (
//            [name] => models/gemini-2.0-flash
//            [version] => 2.0
//            [displayName] => Gemini 2.0 Flash
//            [description] => Gemini 2.0 Flash
//            ...
//        )
//    [1] => Gemini\Data\Model Object
//        (
//            [name] => models/gemini-2.5-pro-preview-05-06
//            [version] => 2.5-preview-05-06
//            [displayName] => Gemini 2.5 Pro Preview 05-06
//            [description] => Preview release (May 6th, 2025) of Gemini 2.5 Pro
//            ...
//        )
//    [2] => Gemini\Data\Model Object
//        (
//            [name] => models/text-embedding-004
//            [version] => 004
//            [displayName] => Text Embedding 004
//            [description] => Obtain a distributed representation of a text.
//            ...
//        )
//]

$response->nextPageToken // Chltb2RlbHMvZ2VtaW5pLTEuMC1wcm8tMDAx

获取模型信息

获取模型的详细信息，如版本、显示名称、输入 token 限制等。

use Gemini\Laravel\Facades\Gemini;

$response = Gemini::models()->retrieve('models/gemini-2.5-pro-preview-05-06');

$response->model;
//Gemini\Data\Model Object
//(
//    [name] => models/gemini-2.5-pro-preview-05-06
//    [version] => 2.5-preview-05-06
//    [displayName] => Gemini 2.5 Pro Preview 05-06
//    [description] => Preview release (May 6th, 2025) of Gemini 2.5 Pro
//    ...
//)

故障排除（Troubleshooting）

超时（Timeout）

向 API 发送请求时可能会遇到超时问题。默认超时时间取决于所使用的 HTTP 客户端。

你可以在 config/gemini.php 文件中配置超时时间：

return [
    'api_key' => env('GEMINI_API_KEY'),
    'base_url' => env('GEMINI_BASE_URL', 'https://generativelanguage.googleapis.com/v1beta/'),
    'request_timeout' => env('GEMINI_REQUEST_TIMEOUT', 30), // 将超时时间增加到 30 秒
];

或者在 .env 文件中设置：

GEMINI_REQUEST_TIMEOUT=60

测试（Testing）

本包提供了一个 Gemini\Client 类的模拟（fake）实现，允许你模拟 API 响应。

为了测试你的代码，请确保在测试用例中将 Gemini\Client 类替换为 Gemini\Testing\ClientFake 类。

模拟响应会按照创建模拟客户端时提供的顺序依次返回。

所有响应都包含一个 fake() 方法，让你只需提供与当前测试相关的参数，即可轻松创建响应对象。

use Gemini\Laravel\Facades\Gemini;
use Gemini\Responses\GenerativeModel\GenerateContentResponse;

Gemini::fake([
    GenerateContentResponse::fake([
        'candidates' => [
            [
                'content' => [
                    'parts' => [
                        [
                            'text' => 'success',
                        ],
                    ],
                ],
            ],
        ],
    ]),
]);

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')->generateContent('test');

expect($result->text())->toBe('success');

对于流式（streamed）响应，你可以选择性地提供一个包含模拟响应数据的资源（resource）。

use Gemini\Laravel\Facades\Gemini;
use Gemini\Responses\GenerativeModel\GenerateContentResponse;

Gemini::fake([
    GenerateContentResponse::fakeStream(),
]);

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')->streamGenerateContent('Hello');

expect($response->getIterator()->current())
    ->text()->toBe('In the bustling city of Aethelwood, where the cobblestone streets whispered');

在请求发送后，你可以使用多种方法来验证是否发送了预期的请求：

use Gemini\Laravel\Facades\Gemini;
use Gemini\Resources\GenerativeModel;
use Gemini\Resources\Models;

// 断言已发送列出模型（list models）的请求
Gemini::models()->assertSent(callback: function ($method) {
    return $method === 'list';
});
// 或
Gemini::assertSent(resource: Models::class, callback: function ($method) {
    return $method === 'list';
});

Gemini::generativeModel(model: 'gemini-2.0-flash')->assertSent(function (string $method, array $parameters) {
    return $method === 'generateContent' &&
        $parameters[0] === 'Hello';
});
// 或
Gemini::assertSent(resource: GenerativeModel::class, model: 'gemini-2.0-flash', callback: function (string $method, array $parameters) {
    return $method === 'generateContent' &&
        $parameters[0] === 'Hello';
});


// 断言已发送 2 次生成式模型（generative model）请求
Gemini::assertSent(resource: GenerativeModel::class, model: 'gemini-2.0-flash', callback: 2);
// 或
Gemini::generativeModel(model: 'gemini-2.0-flash')->assertSent(2);

// 断言未发送任何生成式模型请求
Gemini::assertNotSent(resource: GenerativeModel::class, model: 'gemini-2.0-flash');
// 或
Gemini::generativeModel(model: 'gemini-2.0-flash')->assertNotSent();

// 断言未发送任何请求
Gemini::assertNothingSent();

若要编写期望 API 请求失败的测试，你可以将一个 Throwable 对象作为响应提供。

use Gemini\Laravel\Facades\Gemini;
use Gemini\Exceptions\ErrorException;

Gemini::fake([
    new ErrorException([
        'message' => 'The model `gemini-basic` does not exist',
        'status' => 'INVALID_ARGUMENT',
        'code' => 400,
    ]),
]);

// 将抛出 `ErrorException`
Gemini::generativeModel(model: 'gemini-2.0-flash')->generateContent('test');

Laravel Gemini AI 快速上手指南

环境准备

• PHP 版本：8.1 或更高
• Laravel 版本：9、10、11 或 12

💡 建议使用国内 Composer 镜像加速安装（如阿里云镜像）：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

安装步骤

1. 使用 Composer 安装扩展包：

composer require google-gemini-php/laravel

2. 执行安装命令，生成配置文件：

php artisan gemini:install

该命令会在 config/gemini.php 创建配置文件，并在 .env 中自动添加如下环境变量占位符：

GEMINI_API_KEY=
GEMINI_BASE_URL=
GEMINI_REQUEST_TIMEOUT=

3. 获取 API 密钥
   访问 Google AI Studio 创建并复制你的 API Key，填入 .env 文件：

GEMINI_API_KEY=your_api_key_here

基本使用

最简文本生成示例

use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->generateContent('你好，介绍一下你自己');

echo $result->text(); // 输出模型回复

多模态输入（文本 + 图片）

use Gemini\Data\Blob;
use Gemini\Enums\MimeType;
use Gemini\Laravel\Facades\Gemini;

$result = Gemini::generativeModel(model: 'gemini-2.0-flash')
    ->generateContent([
        '这张图片里有什么？',
        new Blob(
            mimeType: MimeType::IMAGE_JPEG,
            data: base64_encode(file_get_contents('path/to/your/image.jpg'))
        )
    ]);

echo $result->text();

✅ 提示：推荐使用 gemini-2.0-flash 或 gemini-2.5-flash 等最新模型以支持全部功能。
⚠️ 注意：v2.0 起已移除 Gemini::geminiPro() 等旧方法，请统一使用 generativeModel() 并传入模型名称字符串。