Ir al contenido
注目

Python Google GenAIのGemini APIのためのSDK

PortelcoreのGemini API用新しい統合Google GenAI SDKの参照ガイドおよび高度な設定

技術的難易度:
0閲覧数

このセクションでは、新しいSDKの文脈を設定し、ライブラリ変更に関する主なユーザーの混乱に対処し、インストールと2つの重要な認証経路をカバーする堅実なガイドを提供します。

1.1. 新しい標準:google-generativeai から google-genai への移行

Sección titulada «1.1. El Nuevo Estándar: Migrando de google-generativeai a google-genai»

Google の生成 AI モデル向け開発エコシステムは進化しました。google-genai ライブラリは、Gemini API やその他の Google 生成 AI モデルとの連携に推奨される公式かつ統一された Python SDK となっています。2025年5月に一般提供(GA)に到達し、従来のライブラリ google-generativeai を置き換えます。

以前のライブラリ google-generativeai は、Python Package Index(PyPI)で「非アクティブ」とマークされ、廃止の道を進んでいます。重大なバグ修正を含むこのパッケージのサポートは、2025年9月末に終了しますが、一部の情報源では同年8月31日に終了する可能性が示唆されています。円滑な移行を確実にするため、開発者にはより早い目標日に向けて対応することを推奨します。

この変更は単なる名前の変更ではなく、開発者のフィードバックを基にした戦略的な統合です。目的は、Google の全生成 AI モデル(Gemini、Veo、Imagen など)へのアクセスを簡素化し、より明確で一貫性のある開発経路を提供する唯一の SDK を作成することでした。新しい SDK google-genai の最も重要な設計上の決定の一つは、手軽に利用できる Gemini 開発者向け API と、エンタープライズ向けの Vertex AI プラットフォームという、2 つの異なるバックエンドサービスに対する単一のインターフェースとして機能することです。

この統一アーキテクチャは、開発者にとってスムーズな参入の足場を提供します。API キーを使って Gemini 開発者向け API に接続すれば、多くの場合無料枠から迅速に始めることができます。アプリケーションが成熟し、より大きなスケーラビリティ、ガバナンス、および他の Google Cloud サービスとの統合が必要になると、主にクライアントの初期化を変更するだけで、最小限のコード変更で Vertex AI バックエンドに切り替えることができます。google-genai SDK は架け橋として機能し、参入障壁を下げながら Google Cloud 上での本番運用への明確な道筋を示します。そのため、従来のライブラリを利用しているすべてのユーザーは、最新機能(Live API や Veo など)、パフォーマンスの向上、そして継続的なサポートにアクセスするために移行することを強く推奨します。

SDKをインストールする前に、Python仮想環境を設定することがベストプラクティスです。これにより、プロジェクトの依存関係が隔離され、他のプロジェクトやシステムパッケージとの競合を防ぐことができます。

venv を使って仮想環境を作成し、アクティベートするには:

Ventana de terminal
# En macOS/Linux
python3 -m venv gemini-env
source gemini-env/bin/activate
# En Windows
py -m venv gemini-env
.\gemini-env\Scripts\activate

仮想環境がアクティベートされたら、pip を使用して Google Gen AI SDK の最新バージョンをインストールできます。--upgrade フラグを使用することで、最新バージョンが取得できることを保証します。

Ventana de terminal
pip install --upgrade google-genai

Python バージョンの要件を確認することは極めて重要です。google-genai SDK には Python 3.9 以上が必要です。非互換のバージョンを使用すると、インストール時または実行時に予期しないエラーが発生する可能性があります。

高パフォーマンスな非同期処理が必要なアプリケーションでは、デフォルトの httpx の代わりに aiohttp を HTTP トランスポートバックエンドとして使用するオプションが SDK に用意されています。これはエクストラとしてインストールできます。

Ventana de terminal
pip install google-genai[aiohttp]

認証は最も重要な構成手順であり、使用するバックエンドサービス(Gemini Developer APIまたはVertex AI上のGemini API)によって方法が異なります。

1.3.1. Gemini Developer API経路(プロトタイピングおよびフリーツイアに推奨)

Sección titulada «1.3.1. La Vía de la API de Desarrollador de Gemini (Recomendada para Prototipos y Nivel Gratuito)»

Geminiで構築を開始する最も迅速な方法です。Google AI Studioから無料で取得できるAPIキーが必要です。

APIキーを取得するプロセスは以下の通りです:

  1. https://ai.google.dev/ に移動し、Googleアカウントでログインしてください。
  2. 「APIキーを取得する」をクリックします。
  3. 新しいまたは既存のGoogle CloudプロジェクトでAPIキーを作成します。
  4. APIキーが自動的に生成されます。

APIキーは機密情報であり、パスワードと同じように扱う必要があります。セキュアに保存し、クライアントサイドコードやパブリックバージョンコントロールシステムにコミットしてはなりません。

キーを使用する最も安全で推奨される方法は、環境変数として設定することです。SDK は、GOOGLE_API_KEY または GEMINI_API_KEY 環境変数を自動的に検出して使用するよう設計されています。両方が設定されている場合、GOOGLE_API_KEY が優先されます。

環境変数を設定するには:

  • Linux/macOS (bash):

    Ventana de terminal
    export GOOGLE_API_KEY='SU_CLAVE_DE_API_AQUI'
    # Agregue esta línea a su archivo ~/.bashrc o ~/.zshrc para que sea permanente
  • Windows の場合: システム設定の「環境変数」グラフィカルインターフェースを使用して、値としてキーを設定した GOOGLE_API_KEY という名前の新しいユーザー変数またはシステム変数を追加します。

1.3.2. Vertex AIパス(プロダクションおよびGoogle Cloud統合向け推奨)

Sección titulada «1.3.2. La Vía de Vertex AI (Recomendada para Producción e Integración con Google Cloud)»

Google Cloudのエンタープライズ機能を活用するプロダクション規模のアプリケーションには、Gemini APIをVertex AIを介して使用することをお勧めします。このアプローチには、課金が有効なGoogle Cloudプロジェクトが必要です。

初期構成手順には以下が含まれます:

  1. Google Cloudプロジェクトの作成または選択
  2. プロジェクトで課金が有効になっていることを確認してください。
  3. プロジェクトで Vertex AI API(aiplatform.googleapis.com)を有効にします。

Vertex AIの認証は2つの方法で行えます:

  • アプリケーションデフォルト資格情報(ADC)(プロダクション向け推奨): これはほとんどのプロダクションシナリオで推奨される方法です。ADCは環境に応じて資格情報を自動的に検出します。ローカル開発環境では、gcloud CLIコマンドを実行して構成できます :

    Ventana de terminal
    gcloud auth application-default login

    Google Cloud環境で実行する場合(例:Cloud Run、Google Kubernetes Engine、Cloud Functions)、ADCは自動的にそのリソースに接続されたサービスアカウントを使用するため、キーマネジメントの必要がありません。

  • API キー(Vertex でのテスト用): Vertex AI エンドポイントで認証するために API キーを使用することは可能ですが、開発者向け API よりも複雑です。サービスアカウントの API キー作成を有効にする組織レベルの権限、適切なロール(例:Vertex AI User)を持つサービスアカウントの作成、そのサービスアカウントに制限された API キーの作成が必要です。この複雑さのため、この方法は一般的なアプリケーション開発というより、特定のテストシナリオで使用されることが一般的です。

1.4. クライアント初期化:モデルへの接続

Sección titulada «1.4. Inicialización del Cliente: Conectándose al Modelo»

認証の設定が完了したら、次のステップは genai.Client オブジェクトをインスタンス化することです。統合 SDK は、2 つのバックエンドのいずれにも対応可能な単一のクライアントを提供することで、この作業を簡素化します。

以下は、クライアント初期化の4つの主要なシナリオです。

  • シナリオ1: Gemini開発者API(明示的なキー) 環境変数を設定したくないノートブックやクイックスクリプトで使いやすい方法です。APIキーは引数として直接渡されます。

    from google import genai
    client = genai.Client(api_key="SU_CLAVE_DE_API_AQUI")
  • シナリオ2: Gemini Developer API(環境変数) これはアプリケーションコードにとって最もクリーンで推奨されるアプローチであり、コードから認証情報を分離します。クライアントは自動的に環境変数 GOOGLE_API_KEY を検出して使用します。

    # Asegúrese de que la variable de entorno GOOGLE_API_KEY esté configurada
    from google import genai
    client = genai.Client()
  • シナリオ3: Vertex AI API(明示的パラメーター) Vertex AIに接続するには、フラグ vertexai を True に設定し、プロジェクトIDとロケーションを指定します。この方法では、認証のためにアプリケーションのデフォルト認証情報(ADC)が自動的に使用されます。

    from google import genai
    client = genai.Client(vertexai=True, project="su-id-de-proyecto-gcp", location="us-central1")
  • シナリオ4: Vertex AI API(環境変数) Vertex AIの代替として、構成を環境変数に外部化できます。クライアントはこれらの変数を検出し、Vertex AIバックエンドを使用するように構成されます。

    Ventana de terminal
    export GOOGLE_GENAI_USE_VERTEXAI=true
    export GOOGLE_CLOUD_PROJECT='su-id-de-proyecto-gcp'
    export GOOGLE_CLOUD_LOCATION='us-central1'
    # El cliente se configurará automáticamente para Vertex AI
    from google import genai
    client = genai.Client()

これらの方法の要約は以下の通りです。

表1: クライアント初期化クイックリファレンス

使用ケースPythonコード必要な環境変数ノート
明示的なキー付き開発者APIclient = genai.Client(api_key="SU_CLAVE...")なしノートブックやクイックテストに役立ちます。プロダクションコードでは避けてください。
開発者API(環境変数)client = genai.Client()GOOGLE_API_KEY または GEMINI_API_KEYクリーンでセキュアなアプリケーションコードに最適な方法です。
明示的なパラメータでVertex AIclient = genai.Client(vertexai=True, project="...", location="...")なし(ADCを使用)Vertex AIを明示的に指定する方法。ADC認証(gcloud auth...)が必要です。
環境変数でVertex AIclient = genai.Client()GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATIONコードにパラメータを指定せずにClientを設定します。ADC認証が必要です。

パート2:コア機能:テキストとチャット

Sección titulada «Parte 2: Capacidades Principales: Texto y Chat»

このパートでは、最も一般的な使用ケースであるテキストの生成と会話エージェントの構築について説明します。主なメソッドとオブジェクトの詳細が記載されています。

2.1. コンテンツの生成: generate_content メソッド

Sección titulada «2.1. Generando Contenido: El Método generate_content»

シングルターン生成タスク全般に対する主要なメソッドは client.models.generate_content() です。この多用途なメソッドは、Geminiモデルとの対話の基礎となります。

基本的な使い方では、単純な文字列を contents として提供し、使用するモデル名(例:gemini-2.5-flash)を指定します。

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado como se describió anteriormente
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Explica brevemente por qué el cielo es azul."
)
print(response.text)

単純な文字列を渡すのは便利ですが、SDKが内部的に使用しているデータ構造を理解することが重要です。SDKはすべての入力を、types.Content オブジェクトと types.Part オブジェクトで構成される標準化された構造に変換します。この構造を理解することは、マルチモーダルなプロンプトや関数呼び出しといったSDKの高度な機能を活用するための鍵となります。

  • types.Content: 会話における単一のメッセージまたはターンを表します。主な属性は2つあります:role(通常、入力は ‘user’、出力は ‘model’)と parts のリストです。
  • types.Part: Content オブジェクト内の1つのデータ片を表します。パートにはテキスト、画像データ、ファイル参照、関数呼び出しなどが含まれます。

SDKは引数 contents に対するさまざまな入力タイプを賢く処理し、適切な Content/Part 形式に変換します:

  • 単一の文字列:contents='¿Por qué el cielo es azul?' は1つのテキスト Part を持つ UserContent に変換されます。
  • 文字列のリスト:contents=['Pregunta 1', 'Pregunta 2'] は2つのテキスト Part を含む1つの UserContent に変換されます。
  • types.Part オブジェクト:画像データの指定など、より詳細な制御が可能です。
  • 完全に構成された types.Content オブジェクト:メッセージの役割とコンテンツを最大限に制御できます。

生成されたレスポンスにアクセスするには、便利なアクセサー response.text が最も簡単な方法です。ただし、このアクセサーは単一のテキストパートからなる単純なレスポンスに対してのみ機能することを知っておくことが重要です。レスポンスがセーフティフィルターによってブロックされた場合、複数の候補を含む場合、またはテキスト以外のデータ型を含む場合、response.text にアクセスするとエラーが発生します。運用環境で最も堅牢で安全な方法は、候補とそのパートに直接アクセスすることです:

try:
# Método robusto para acceder al texto
text_response = response.candidates.content.parts.text
print(text_response)
except (IndexError, AttributeError):
# Manejar el caso en que no hay respuesta de texto válida
print("No se pudo obtener una respuesta de texto válida.")
# Se puede inspeccionar response.prompt_feedback para ver si fue bloqueado
print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}")

2.2. リアルタイムフィードバックのためのストリーミング応答

Sección titulada «2.2. Respuestas en Streaming para Retroalimentación en Tiempo Real»

チャットボットなどのインタラクティブなアプリケーションでは、モデルの応答をストリーミングすることで、ユーザー体験が大幅に向上します。全体の応答が生成されるのを待つ代わりに、テキストのチャンクが到着するたびに表示され、即時のフィードバックが提供されます。

この機能は generate_content_stream() メソッドで実現されます。このメソッドは、モデルによってレスポンスの断片が生成されるたびにそれを出力するイテレーターを返します。

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
response_stream = client.models.generate_content_stream(
model="gemini-2.0-flash",
contents="Escribe un poema largo sobre el océano y sus misterios."
)
print("Respuesta del modelo:")
for chunk in response_stream:
print(chunk.text, end="")
print() # Para una nueva línea al final

2.3. コンタクトAIをマスターする:チャットインターフェース

Sección titulada «2.3. Dominando la IA Conversacional: La Interfaz de Chat»

SDKは、複数ターンの会話を管理するための2つの主要なメカニズムを提供します。1つのアプローチは、会話履歴を手動で管理することです。各ターンを表す Content オブジェクトのリストを構築し、各呼び出しで generate_content() に渡します。柔軟ではありますが、この方法は煩雑になる可能性があります。

チャットボットを作成するための推奨され、最も便利なアプローチは、client.chats が提供するステートフルなチャットインターフェースを利用することです。このトップレベルオブジェクトは履歴管理を抽象化し、アプリケーションコードを大幅に簡素化します。これはSDKにおける意図的な設計判断です:一般的なユースケース(チャット)向けに、高レベルでステートフルな抽象化(client.chats)を提供することで、低レベルかつステートレスな generate_content メソッドと比較して開発を大幅に簡略化します。

チャットインターフェースを使用するワークフローは次のとおりです:

  1. チャットセッションの初期化:client.chats.create() を使用して新しい会話を開始します。モデルを指定でき、必要に応じて会話の文脈づけのための初期履歴を提供できます。
  2. メッセージの送信:chat.send_message() メソッドを使用して、ユーザーの次のメッセージを送信します。SDKは状態を自動的に管理し、ユーザーのメッセージとその後のモデルのレスポンスを会話履歴に追加します。
  3. 履歴にアクセスする:いつでもchat.get_history()を使用して、会話の完全な履歴を取得できます。

以下のマルチターン会話の完全な例を参照してください:

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Crear una nueva sesión de chat
chat_session = client.chats.create(
model="gemini-2.0-flash"
)
# 2. Enviar el primer mensaje
print("Usuario: Hola, ¿puedes ayudarme a planificar un viaje a la luna?")
response = chat_session.send_message("Hola, ¿puedes ayudarme a planificar un viaje a la luna?")
print(f"Modelo: {response.text}\n")
# 3. Enviar un segundo mensaje de seguimiento
print("Usuario: ¿Qué tres cosas debería empacar?")
response = chat_session.send_message("¿Qué tres cosas debería empacar?")
print(f"Modelo: {response.text}\n")
# 4. Mostrar el historial completo de la conversación
print("--- Historial de la Conversación ---")
for message in chat_session.get_history():
# El rol y el texto están en message.role y message.parts.text
role = "Usuario" if message.role == "user" else "Modelo"
print(f"{role}: {message.parts.text}")

モデルの動作を微調整するために、メソッドgenerate_contentはconfigパラメータを受け取り、これはtypes.GenerateContentConfigオブジェクトを取ります。このオブジェクトにより、開発者は生成プロセスのさまざまな側面を制御できます。

最も便利な設定の1つはsystem_instructionです。システム指示は、高レベルのガイダンスを提供するか、会話全体を通じて継続するモデルの個性を設定します。たとえば、モデルに特定のキャラクターとして振る舞うよう指示したり、回答で特定のルールに従うよう指示したりできます。

from google.genai import types
# Asumiendo que 'client' ha sido inicializado
response = client.models.generate_content(
model='gemini-2.0-flash',
contents='¡Ah del barco! Cuéntame un chiste sobre un loro.',
config=types.GenerateContentConfig(
system_instruction='Hablas como un pirata malhumorado y conciso.'
)
)
print(response.text)

システム指示に加えて、モデルの出力の創造性と構造を制御するために調整可能な他のパラメータもいくつかあります。次の表は、最も重要なものを詳細に説明しています。

表2: 主要な生成構成パラメータ

パラメータ説明範囲出力への影響
temperatureトークン選択のランダム性を制御します。0.0 - 1.0値が低いほど(例:0.2)、出力はより決定論的で創造性が低くなります。値が高いほど(例:0.9)、ランダム性と創造性が高まります。
top_p核サンプリング(nucleus sampling)。累積確率がtop_pを超える最小のトークン集合を考慮します。0.0 - 1.00.95のような値は、確率質量の上位95%を占めるトークンのみが考慮されることを意味します。極めて起こりにくいトークンを避けるのに役立ちます。
top_k生成の各ステップで、最も可能性の高いkトークンのみを考慮します。整数1のtop_kは貪欲デコード(greedy)です。40のような値は、選択を最も可能性の高い40トークンに制限します。
candidate_count生成される候補応答の数。整数(例:1-8)同じプロンプトに対して複数の可能な応答を生成します。ユーザーにオプションを提供するのに役立ちます。
max_output_tokens応答で生成できるトークンの最大数。整数出力の長さを制限します。コストと遅延を制御するために不可欠です。
stop_sequences生成されたときに出力を停止する文字列のリスト。文字列のリスト特定のポイントで生成を停止するのに役立ちます。たとえば、文末のマーカーや特定の形式など。
seed生成用のランダムシード。整数シードを指定すると、出力は決定論的で再現可能になります(temperatureが0でない限り)。

パート3: 高度なインタラクション: マルチモーダル性と関数呼び出し

Sección titulada «Parte 3: Interacciones Avanzadas: Multimodalidad y Llamada a Funciones»

このパートでは、Geminiモデルの本当の力を紹介します。非テキスト入力と外部ツールへの接続方法について説明します。

3.1. テキストを超えて: マルチモーダル入力の理解

Sección titulada «3.1. Más Allá del Texto: Comprendiendo las Entradas Multimodales»

Geminiモデルファミリーの特徴的な点の1つは、内在的なマルチモーダル機能です。これは、1つのプロンプトリクエスト内でテキスト、画像、音声、動画などの異なるデータタイプ(「モダリティ」と呼ばれる)を処理および推論できることを意味します。

この機能は、contents引数を複数のPartオブジェクトを含むリストとして構築することで有効になります。それぞれのPartは異なるデータタイプを含むことができます。たとえば、1つのリクエストに画像とその画像に関するテキスト質問の両方を含めることができます。

SDKでは、画像データを扱うための2つの戦略的に異なる方法が提供されています。どちらの方法を選ぶかは、ユースケースの具体的な要件によって異なります。たとえば、ファイルサイズや再利用性が考慮されます。

この2つの方法の違いは、冗長ではなく、異なる運用ニーズに対応するための意図的な設計です。インライン方法は、単回の分析や開発の利便性に優れており、シンプルです。ファイルAPIは、効率性、スケーラビリティ、大容量ファイルの処理が重要な本番環境においては不可欠ですが、追加のアップロードステップが必要です。

メソッド1: インライン画像データ

Sección titulada «Método 1: Datos de Imagen en Línea (Inline)»

この方法は、より小さな画像ファイル(プロンプトとバイトを含む合計リクエストが20 MB未満である必要があります)や、開発のシンプルさに最適です。画像データはgenerate_contentの呼び出しに直接渡されます。

  • ローカルファイルから:画像ファイルはバイナリモード('rb')で読み込まれ、正しいMIMEタイプを指定してtypes.Part.from_bytes()に渡されます。

    import google.genai as genai
    from google.genai import types
    # Asumiendo que 'client' ha sido inicializado
    with open('imagen_scones.jpg', 'rb') as f:
    image_bytes = f.read()
    image_part = types.Part.from_bytes(
    data=image_bytes,
    mime_type='image/jpeg'
    )
    prompt_part = "Describe lo que ves en esta imagen."
    # Combinar imagen y texto en una sola solicitud
    response = client.models.generate_content(
    model='gemini-2.5-flash', # O un modelo de visión como gemini-pro-vision
    contents=[prompt_part, image_part]
    )
    print(response.text)
  • URLから:requestsのようなライブラリを使用して、URLから画像のバイトを取得し、同じ方法で渡すことができます。

このメソッドは、大きな画像ファイル(20MB以上)や、複数のプロンプトリクエストで同じファイルを再利用するシナリオに推奨されます。ファイルAPIを使用すると、各コールごとに同じバイトを再アップロードする必要がありません。

ワークフローは2つのステップから構成されます:

  1. アップロード:client.files.upload()を使用して、ファイルをGoogleのサーバーにアップロードします。このメソッドは、参照として機能するファイルオブジェクトを返します。
  2. 指定:返されたファイルオブジェクトは、generate_contentの呼び出しのcontentsリストに直接渡されます。SDKは、アップロードされたファイルへの参照を解決します。
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar el archivo usando la API de Archivos
print("Cargando archivo...")
sample_file = client.files.upload(
file_path="imagen_grande.png",
display_name="Mi Imagen de Muestra"
)
print(f"Archivo cargado: {sample_file.uri}")
# 2. Usar el archivo cargado en una indicación
prompt = "Analiza esta imagen y describe los objetos principales y su disposición espacial."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=[prompt, sample_file] # Pasar el objeto de archivo directamente
)
print(response.text)
# Opcional: Eliminar el archivo después de su uso
client.files.delete(name=sample_file.name)
print(f"Archivo eliminado: {sample_file.name}")

Files APIを介してアップロードされたファイルは、自動的に削除される前に48時間一時的に保存されます。APIはまた、これらのファイルを管理するためのメソッドも提供しています。例えば、get()、list()、delete()などです。

3.3. 音声および動画と連携する

Sección titulada «3.3. Interacción con Audio y Vídeo»

画像処理のコンセプトは、音声および動画などの他のモダリティに直接拡張されます。これらのファイルは通常大容量であるため、ファイルAPIが主に使用されます。

処理は大容量画像の場合と同じです。

  1. client.files.upload()を使用して、音声ファイル(例:MP3、WAV)または動画ファイル(例:MP4)をアップロードします。
  2. 返されたファイルオブジェクトをgenerate_contentへのプロンプトに含めます。

次の例は、オーディオファイルをアップロードし、モデルに文字起こしを依頼する方法を示しています。

import google.genai as genai
import time
# Asumiendo que 'client' ha sido inicializado
# 1. Cargar un archivo de audio
print("Cargando archivo de audio...")
audio_file = client.files.upload(
file_path="discurso_muestra.mp3",
display_name="Discurso de Muestra"
)
# El procesamiento del archivo puede llevar tiempo, se espera a que esté ACTIVO
while audio_file.state.name == "PROCESSING":
print("Procesando archivo... esperando.")
time.sleep(10)
audio_file = client.files.get(name=audio_file.name)
if audio_file.state.name == "FAILED":
raise ValueError(audio_file.state.name)
# 2. Usar el archivo de audio en una indicación
prompt = "Transcribe el discurso en este archivo de audio."
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=[prompt, audio_file]
)
print("\n--- Transcripción ---")
print(response.text)

関数呼び出し、つまりツールの使用は、言語モデルが外部システムと相互運用できる強力なテクニックです。これは、モデルが固有の知識を超えて、リアルタイムデータをAPIから取得したり、データベースを照会したり、デバイスを制御したりする質問に答えたり、行動を取ったりすることを可能にします。

一般的なワークフローは以下の通りです:

  1. ツールの定義: モデルが呼び出すことのできるツール(Python関数)のセットが定義されます。この定義には、関数名、その機能の説明、パラメータのスキーマが含まれます。
  2. ツールをモデルに渡す:定義したツールのリストを、generate_contentの呼び出し時にモデルに渡します。
  3. モデルが呼び出しを決定:モデルはユーザーのプロンプトを分析し、提供されたツールのいずれかが回答に役立つと判断した場合、テキストを生成する代わりに、function_call型のPartオブジェクトを含む応答を返します。このオブジェクトは、呼び出す関数の名前とその引数を指定します。
  4. 関数を実行:アプリケーションコードはこのfunction_callを検出し、指定された引数で対応するPython関数を実行し、結果を取得します。
  5. 結果をモデルに返す:会話履歴に加え、関数実行結果(types.Part.from_function_response()でラップされたもの)を渡して、generate_contentへの2回目の呼び出しを行います。
  6. 最終的な応答: モデルは関数の結果を使用して、ユーザーに対する最終的な自然言語応答を生成します。

調査の断片では、エンドツーエンドの関数呼び出しコード例は提供されていませんが、function_callおよびfunction_response用のPartオブジェクトの構造は、この高度なパターンを実装するための基盤となります。


パート4: プロダクション準備: エラー処理、セキュリティ、管理

Sección titulada «Parte 4: Preparación para Producción: Manejo de Errores, Seguridad y Gestión»

この最終パートでは、信頼性があり、責任あるアプリケーションを構築するために必要な重要な情報が提供されます。

プロダクション環境では、強力なエラー処理は必須です。API呼び出しは、無効な資格情報、ネットワークの問題、クォータの枯渇、または不正な入力などの理由で失敗する可能性があります。

このSDKはPythonの標準例外システムを使用します。API関連のほとんどのエラーは、google.api_core.exceptionsモジュールの例外を捕捉するtry...exceptブロック、または可能であればerrors.APIErrorのようなより具体的なクラスを利用して捕捉できます。

from google.api_core import exceptions as core_exceptions
import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
try:
response = client.models.generate_content(
model="nombre-de-modelo-invalido",
contents="¿Cuál es tu nombre?"
)
print(response.text)
except core_exceptions.GoogleAPICallError as e:
# 'e' es una superclase para muchos errores de API
print(f"Ha ocurrido un error en la API: {e}")
# En muchos casos, 'e' tendrá atributos como 'code' y 'message'
# aunque esto puede variar. Se recomienda inspeccionar el objeto de excepción.
except core_exceptions.NotFound as e:
# Un error más específico si se sabe qué buscar
print(f"Error: Recurso no encontrado. ¿Es correcto el nombre del modelo? - {e.message}")
except core_exceptions.ResourceExhausted as e:
# Específico para errores de cuota
print(f"Error: Se ha excedido la cuota de la API. - {e.message}")

例外をキャッチする際、例外オブジェクトにはログ記録やデバッグに役立つ情報が含まれることが多く、ステータスコードや説明的なメッセージが含まれます。

エラーメッセージは開発者にとって有用ですが、逆手に取られることもあるため、注意が必要です。これらは、悪意のある攻撃者が防御機構を回避するのを助ける可能性のある内部の実装詳細を漏洩する可能性があります。例えば、セーフティ検証エラーメッセージの分析から、内部のしきい値や防御メカニズムが判明する可能性があります。したがって、バックエンドではエラーを徹底的にログに記録すべきですが、エンドユーザーに表示される情報は注意深く制御する必要があります。一般的に、「あなたの要求の処理中にエラーが発生しました」といった一般的なメッセージを表示するのが安全です。

以下の表は、一般的なAPIエラーコードとその解決策をまとめています。

表3: 一般的なAPIエラーコードと解決策

HTTPコード状態おそらくの原因Pythonでの推奨アクション
400INVALID_ARGUMENTリクエストボディが不正です(例:不適切なタイプのパラメータ、必要なフィールドが欠落しているなど)。GenerateContentConfigのパラメータとcontentsの形式が正しいことを確認します。モデルが要求された機能と互換性があることを確認してください。
403PERMISSION_DENIEDAPIキーが正しくない、必要な権限がない、または制限されたリソースにアクセスしようとしています(例:カスタムチューニングされたモデルなど)。APIキー(またはVertexのADC認証)が正しく設定されており、必要な権限があることを確認してください。
429RESOURCE_EXHAUSTEDAPIのレートリミット(分間リクエスト数)を超えました。リトライロジックに指数バックオフを実装してください。必要に応じて、アプリケーションにクォータ増加をリクエストしてください。
500INTERNALGoogle側で予期しないエラーが発生しました。場合によっては非常に長い入力コンテキストが原因となることがあります。プロンプトの長さを短縮してください。少し待ってからリクエストを再試行してください。問題が解決しない場合は、一時的に別のモデルに切り替えることを検討してください。
503UNAVAILABLEサービスが一時的に過負荷または利用不可になっています。少し待ってから指数バックオフ戦略を使用してリクエストを再試行してください。問題が解決しない場合は、問題を報告してください。

Gemini APIには、有害なコンテンツをフィルタリングするための組み込みのセーフティ機能が含まれています。これらの機能は、開発者がより安全で責任あるアプリケーションを構築するのを支援することを目的としています。

APIはコンテンツを4つの主要な有害カテゴリに分類します:

  • 嫌がらせ(HARM_CATEGORY_HARASSMENT)
  • 憎悪の扇動(HARM_CATEGORY_HATE_SPEECH)
  • 露骨な性的コンテンツ(HARM_CATEGORY_SEXUALLY_EXPLICIT)
  • 危険なコンテンツ(HARM_CATEGORY_DANGEROUS_CONTENT)

各カテゴリーについて、モデルはコンテンツが安全でない確率を割り当てます。デフォルトでは、APIはこれらのカテゴリーでMEDIUMまたはHIGHの確率で安全でないとされるプロンプトと応答をブロックします。

開発者は、リクエストごとにSafetySettingオブジェクトのリストをsafety_settingsパラメータに渡すことで、このデフォルト設定を上書きできます。これにより、各カテゴリーのブロックしきい値を細かく制御できます。

from google.genai import types
# Asumiendo que 'client' ha sido inicializado
# Ejemplo: Relajar el umbral para el acoso, pero mantener el predeterminado para otros.
# ¡Use esta configuración con precaución y solo si es necesario para su caso de uso!
safety_config =
try:
response = client.models.generate_content(
model='gemini-2.0-flash',
contents="Escribe un diálogo entre dos personajes que están discutiendo acaloradamente.",
safety_settings=safety_config
)
print(response.text)
except ValueError:
# A menudo, una respuesta bloqueada puede generar un ValueError al intentar acceder a.text
print("La respuesta fue bloqueada o está vacía.")
# Inspeccionar la retroalimentación de seguridad para depurar
print(f"Razón del bloqueo del prompt: {response.prompt_feedback.block_reason}")
if response.candidates:
print(f"Calificaciones de seguridad del candidato: {response.candidates.safety_ratings}")

応答が空に見える場合やエラーが発生した場合は、セキュリティフィードバックを確認することが重要です。応答オブジェクトには、入力プロンプト用のprompt_feedbackと、生成された応答用のcandidates.safety_ratingsが含まれます。これらの属性により、コンテンツがブロックされたかどうか、またその理由が判明するため、デバッグに不可欠です。

次の表は、さまざまなブロッキングしきい値の意味を説明しています。

表4: セーフティ構成のしきい値

API定数Google AI Studioでの設定説明
HARM_BLOCK_THRESHOLD_UNSPECIFIEDN/Aしきい値が指定されていません。モデルのデフォルトのしきい値が使用されます。
BLOCK_NONEブロックしない安全でない確率に関係なく、コンテンツをブロックしない。非常に注意深く使用する必要があります。
BLOCK_ONLY_HIGHいくつかのブロックコンテンツが安全でない確率がHIGHの場合にのみブロックします。
BLOCK_MEDIUM_AND_ABOVE一部のブロック(ほとんどのモデルのデフォルト)コンテンツが安全でない確率がMEDIUMまたはHIGHの場合にブロックします。
BLOCK_LOW_AND_ABOVEほとんどのブロックコンテンツが安全でない確率がLOW、MEDIUM、またはHIGHの場合にブロックします。

SDKは、利用可能なモデルとその機能を発見するためのプログラマティックな方法を提供します。これは、異なるモデルに適応できるアプリケーションを構築する場合や、モデルの機能を確認する前に使用する場合に役立ちます。

client.models.list()メソッドは、利用可能なモデルに対するイテレータを返します。

Python

import google.genai as genai
# Asumiendo que 'client' ha sido inicializado
print("Modelos disponibles:")
for model in client.models.list():
# El objeto 'model' contiene metadatos detallados
print(f" - Nombre: {model.name}")
print(f" - Nombre para mostrar: {model.display_name}")
print(f" - Métodos soportados: {model.supported_generation_methods}")
# Verificar si el modelo soporta chat (create_chat)
if 'create_chat' in model.supported_generation_methods:
print(" - ¡Este modelo soporta chat!")
print("-" * 20)

この機能は、リスト要求の設定でquery_base=Falseを設定することで、ユーザーがファインチューニングしたモデルを特に一覧表示するためにも使用できます。これにより、アプリケーションはカスタムモデルを動的に発見して利用できます。


パート5: エンバイロメントの検証とテクニカルチェックリスト

Sección titulada «Parte 5: Validación del Entorno y Checklist Técnica»

Portelcoreのテナントで統合SDKgoogle-genaiに基づく統合のプロビジョニングを完了するため、以下の技術的マイルストーンの達成を確認してください:

  • テナントのすべてのスクリプトを、廃止予定のgoogle-generativeaiライブラリから新しいgoogle-genai標準に移行しました。 ✓
  • APIキーは、GOOGLE_API_KEY環境変数のみ、またはGoogle Cloudのシークレットマネージャーで難読化して管理し、平文では記述しません。 ✓
  • 指数関数的バックオフ(exponential backoff)を伴う再試行ポリシーで、ステータスコード429(Resource Exhausted)を捕捉する堅牢な例外制御(google.api_core.exceptions)を実装します。 ✓
  • 温度パラメータと安全しきい値(safety_settings)は、portelcore.comドメインのユースケースに応じて公式にパラメータ化されています。 ✓