Posted inAI

Google Gemini APIチュートリアル：30分でアプリにAI機能を組み込む

Google Gemini APIチュートリアル：30分でアプリにAI機能を組み込む

多くのチュートリアルが触れない問題

Geminiについて聞いたことがあり、試してみたいと思ったものの、壁にぶつかった経験があるのではないでしょうか。公式ドキュメントは、どのモデルを選ぶべきか、どのSDKをインストールすべきか、マルチモーダル入力がどう機能するかをすでに知っていることを前提としています。気づけばブラウザのタブが15個開いているのに、動くコードが一行も書けていない——そんな状況になりがちです。

私もサイドプロジェクトにGeminiを組み込もうとした最初のころ、同じ経験をしました。本当に役に立ったのは、まず3つのコア概念をしっかり理解すること。そして、サイレントに失敗するコピペサンプルではなく、実際に動くコードを書くことでした。

このガイドはまさにその点を解説します。読み終えるころには、Geminiを呼び出すPythonスクリプトが動く状態になり、どのモデルをいつ使うべきかを理解し、テキスト・画像・ストリーミングレスポンスの扱い方もわかるようになります。

最初に押さえておくべきコア概念

1. Geminiモデルファミリー

Googleはいくつかのモデルを提供しており、それぞれコストとパフォーマンスのトレードオフが異なります：

  • Gemini 2.0 Flash — 高速かつ安価。スケールでのスピードが求められる本番環境に最適。
  • Gemini 1.5 Pro — より大きなコンテキストウィンドウ（最大100万トークン）、高い推論能力、コストも高め。長文書や複雑な分析に使用。
  • Gemini 1.5 Flash — FlashとProのバランス型。ほとんどのユースケースに適したデフォルト選択肢。

初級開発者のプロジェクトの90%では、gemini-2.0-flashから始めましょう。高速で無料枠も十分に充実しており、お金をかけずにプロトタイプを作ることができます。

2. マルチモーダル入力

ほとんどのAPIはテキストのみを受け付けますが、Geminiはテキスト・画像・音声・動画・ドキュメントをすべて同じリクエストでネイティブに処理できます。別のビジョンエンドポイントも追加SDKも不要。テキストプロンプトと一緒に画像のバイトデータを渡すだけです。

3. 2つのSDKアプローチ

GeminiにはPythonライブラリが2つあります：

  • google-genai — 新しい推奨SDK。よりクリーンなAPI設計で、ストリーミング・非同期・現行モデルすべてをサポート。
  • google-generativeai — 旧来のSDK。現在も動作しますが、新機能のサポートは段階的に縮小されています。

新規開発にはgoogle-genaiを使いましょう。このチュートリアルもそれを使用しています。

実践ハンズオン

ステップ1：APIキーの取得

Google AI Studioにアクセスし、Googleアカウントでサインインして、APIキーを取得をクリックします。キーをコピーしておきましょう——すぐに使います。

無料枠では、Flashモデルで1分あたり15リクエスト、1日100万トークンが利用できます。実際のプロジェクトを構築・テストするには十分すぎるほどです。

ステップ2：SDKのインストール

pip install google-genai

仮想環境を使う場合（推奨）：

python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate
pip install google-genai

ステップ3：最初のAPI呼び出し

gemini_test.pyというファイルを作成し、以下を追加します：

import os
from google import genai

# ベストプラクティス：キーは環境変数に保存する
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="REST APIとは何かを3文で説明してください。コーディングを始めたばかりの人向けに。"
)

print(response.text)

実行します：

export GEMINI_API_KEY="ここにAPIキーを入力"
python gemini_test.py

1〜2秒以内に、簡潔でわかりやすい説明が返ってくるはずです。

ステップ4：ストリーミングレスポンス

長い出力の場合、ストリーミングを使うと完全なレスポンスを待つ代わりに即座にフィードバックをユーザーに届けられます。チャットインターフェースでは特に重要です。

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

for chunk in client.models.generate_content_stream(
    model="gemini-2.0-flash",
    contents="CSVファイルを解析してdictのリストを返すPython関数を書いてください。"
):
    print(chunk.text, end="", flush=True)

print()  # 最後に改行を出力

各chunk.textはGeminiが生成するにつれてリアルタイムで届きます。完全なレスポンスを5秒以上待つのではなく、500ミリ秒以内に出力が表示され始めます。

ステップ5：画像の解析

画像解析はGeminiが真に際立つ機能です。画像と質問を一緒に渡すだけで、詳細な分析結果が返ってきます。

import os
import httpx
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# URLから画像を取得する
image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/1/12/ThreeTimesMooresTrees.png/1280px-ThreeTimesMooresTrees.png"
image_bytes = httpx.get(image_url).content

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=[
        types.Part.from_bytes(data=image_bytes, mime_type="image/png"),
        "このグラフは何を示していますか？2文で要約してください。"
    ]
)

print(response.text)

ローカルディスクからも画像を読み込めます：

with open("screenshot.png", "rb") as f:
    image_bytes = f.read()

# その後は上記と同様にPart.from_bytesを使用する

ステップ6：マルチターンチャット

チャットボットの構築には会話履歴の管理が必要ですが、SDKが自動的に処理してくれます：

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
chat = client.chats.create(model="gemini-2.0-flash")

# 最初のターン
response = chat.send_message("FastAPIアプリを作っています。最低限必要なセットアップは何ですか？")
print("Gemini:", response.text)

# 2ターン目 — Geminiはコンテキストを記憶している
response = chat.send_message("そこにJWT認証を追加するにはどうすればいいですか？")
print("Gemini:", response.text)

chatオブジェクトは会話履歴を自動的に管理します。過去のメッセージを手動で追跡して送信する必要はありません。

ステップ7：出力の制御

生成パラメータを使うと、Geminiのレスポンスを細かく調整できます。特に重要な3つを紹介します：

from google.genai import types

config = types.GenerateContentConfig(
    temperature=0.2,       # 低いほど決定論的になる（コードに適している）
    max_output_tokens=512, # レスポンスの長さを制限する
    system_instruction="あなたはシニアPython開発者です。簡潔かつ直接的に答えてください。"
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="Pythonのリストとタプルの違いは何ですか？",
    config=config
)

print(response.text)

覚えておくべき主要パラメータ：

  • temperature：0.0〜2.0。事実確認やコードタスクには0.0〜0.3、創作には0.7〜1.0を使用。
  • max_output_tokens：想定外にコストがかかる長大なレスポンスを防ぎます。
  • system_instruction：会話全体のペルソナと振る舞いを設定します。

ステップ8：エラーハンドリングの実装

APIコールは失敗することがあります。レート制限もかかります。常にエラーハンドリングで囲みましょう：

import os
import time
from google import genai
from google.api_core import exceptions

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

def call_gemini_with_retry(prompt: str, retries: int = 3) -> str:
    for attempt in range(retries):
        try:
            response = client.models.generate_content(
                model="gemini-2.0-flash",
                contents=prompt
            )
            return response.text
        except exceptions.ResourceExhausted:
            wait = 2 ** attempt  # 指数バックオフ
            print(f"レート制限中。{wait}秒後にリトライします...")
            time.sleep(wait)
        except exceptions.InvalidArgument as e:
            print(f"不正なリクエスト: {e}")
            break
    return ""

result = call_gemini_with_retry("Pythonのasync/awaitについて説明してください。")
print(result)

次に作るべきもの

基盤ができました。次に取り組む価値がある4つの方向性を紹介します：

  • ドキュメントQ&A：Files APIを使ってPDFをアップロードし、質問を投げかけます。Gemini 1.5 Proは最大100万トークンに対応しているので、大きなドキュメントでも問題ありません。
  • 画像コンテンツモデレーション：ユーザーがアップロードした画像をGeminiに渡し、保存前に不適切なコンテンツをフラグしてもらいます。
  • コードレビューアシスタント：gitのdiffをGeminiに渡し、厳格なシニアレビュアーとして振る舞うシステムプロンプトを設定します。
  • 構造化出力：configでresponse_mime_type="application/json"を使ってJSON出力を強制します——アプリでレスポンスをパースする必要があるときに便利です。

本番環境で実際に機能するパターン

AIコールをパイプラインの一ステップとして扱いましょう——それがプロダクト全体ではありません。プロンプトはバージョン管理してください。何か問題が起きたときにデバッグできるよう、すべてのリクエストとレスポンスをログに残しましょう。APIがダウンしたときのフォールバックも常に用意しておきます。

gemini-2.0-flashから始め、レイテンシと品質を測定し、Flashで本当に対応できないケースが出たときだけProにアップグレードしましょう。ほとんどの場合、Flashで十分です。

Google AI Studioのプレイグラウンドもブックマークしておく価値があります——コードに組み込む前に、インタラクティブにプロンプトをプロトタイプしましょう。試行錯誤のサイクルを大幅に削減できます。

Share:
Tags: