1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@automation2025(frencia)

Google Gen AI SDK と Gemini APIで始める開発入門

Posted at

はじめに

Google Gen AI SDKは、Google のGeminiモデルをNode.jsやPython、Javaなどから簡単に扱える公式SDKで、テキスト生成・マルチモーダル入力・埋め込み・ツール呼び出しなどに対応しています。
ここでは、@google/genaiを中心にJavaScript/TypeScriptの例だけを用いて15章構成で実践的な使い方を解説します。

第1章 Google Gen AI SDKとは

Google Gen AI SDKは、Gemini APIおよびVertex AI上の生成モデルを、認証処理やレスポンス整形を含めて簡潔なコードで呼び出せる公式クライアントライブラリ群です。
JavaScriptでは@google/genai、Pythonではgoogle-genai、Javaではjava-genaiといったパッケージとして共通の概念を共有しており、「モデルへプロンプトを送り、テキストや埋め込みを受け取る」という一貫した体験を提供します。

# JavaScript SDK の導入
npm install @google/genai

第2章 APIキーとGoogle AI Studio

Gemini APIを利用するには、Google AI Studioでプロジェクトを作成し、Gemini APIキーを発行します。
APIキーはソースコードに埋め込まず.envで管理し、サーバーサイドからSDKに渡す形にすることで、秘密情報を安全に扱いながら開発できます。

# .env
GEMINI_API_KEY="ここにAI Studioで発行したキー"

// config/genai.ts
import {GoogleGenAI} from '@google/genai';

if (!process.env.GEMINI_API_KEY) {
  throw new Error('GEMINI_API_KEY is not set');
}

export const ai = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY,
});

第3章 モデルとモデル名の選び方

Gen AI SDKではmodel文字列で利用するGeminiモデルを指定し、用途に応じて高速なFlash系モデルや高精度なPro系モデルを切り替えます。
たとえばgemini-2.0-flashは応答速度重視のAPI向け、gemini-1.5-proは長文や複雑な推論タスク向けなど、速度・コスト・品質のトレードオフを踏まえて選択することが重要です。

// modelConfig.ts
export const TEXT_MODEL = 'gemini-2.0-flash';
export const CHAT_MODEL = 'gemini-1.5-flash';
export const EMBEDDING_MODEL = 'gemini-embedding-001';

第4章 テキスト生成の基本（generateContent）

テキスト生成の基本はai.models.generateContentで、プロンプト文字列や構造化contentsを渡し、モデルの応答テキストを受け取ります。
config内でmaxOutputTokensやtemperatureを指定することで、文章の長さや創造性の度合いを調整し、要約・翻訳・文章案内などさまざまなタスクに対応できます。

// src/textGenerate.ts
import {ai} from './config/genai';
import {TEXT_MODEL} from './modelConfig';

export async function generateSummary(text: string) {
  const res = await ai.models.generateContent({
    model: TEXT_MODEL,
    contents: `次の文章を日本語で3行に要約してください。\n\n${text}`,
    config: {
      maxOutputTokens: 256,
      temperature: 0.7,
    },
  });

  const output = res.text;
  console.log(output);
  return output;
}

第5章 ストリーミング応答（generateContentStream）

長い文章生成やチャットUIでは、レスポンスを一括で待つよりも少しずつ画面に表示する方が体感速度が大幅に向上します。
generateContentStreamはAsync Iteratorとしてチャンクを返すため、ループで順次テキストを取り出しながら、CLIなら標準出力へ、Webならイベントストリームとしてリアルタイム表示できます。

// src/streamGenerate.ts
import {ai} from './config/genai';

export async function streamStory(prompt: string) {
  const stream = await ai.models.generateContentStream({
    model: 'gemini-2.0-flash',
    contents: prompt,
  });

  for await (const chunk of stream.stream) {
    const text = chunk.text();
    process.stdout.write(text);
  }
}

第6章 チャット形式と履歴管理

チャットボットでは、これまでの会話履歴をcontents配列としてモデルに渡すことで、文脈を踏まえた自然な応答を得られます。
roleに'user'や'model'を付けてメッセージを時系列で並べ、新しいユーザー入力を末尾に追加してからAPIを呼び出す、というサイクルで会話を継続します。

// src/chat.ts
import {ai} from './config/genai';
import {CHAT_MODEL} from './modelConfig';

type ChatMessage = {role: 'user' | 'model'; text: string};

export async function chatWithHistory(
  history: ChatMessage[],
  input: string
) {
  const contents = [
    ...history.map((m) => ({role: m.role, parts: [{text: m.text}]})),
    {role: 'user', parts: [{text: input}]},
  ];

  const res = await ai.models.generateContent({
    model: CHAT_MODEL,
    contents,
  });

  const reply = res.text;
  return [...history, {role: 'user', text: input}, {role: 'model', text: reply}];
}

第7章 画像を含むマルチモーダル入力

Geminiはマルチモーダル対応モデルとして、テキストだけでなく画像などの入力もサポートしており、画像の説明や要約、キャプション生成などに利用できます。
画像ファイルはBase64に変換してinlineDataとして渡し、テキスト部分のプロンプトと組み合わせることで「この画像を解説して」「図表からポイントを抜き出して」といった高度な指示が可能になります。

// src/imageExplain.ts
import {ai} from './config/genai';
import fs from 'fs/promises';

async function fileToBase64(path: string) {
  const data = await fs.readFile(path);
  return data.toString('base64');
}

export async function explainImage(path: string) {
  const base64 = await fileToBase64(path);

  const res = await ai.models.generateContent({
    model: 'gemini-1.5-flash',
    contents: [
      {
        role: 'user',
        parts: [
          {text: 'この画像の内容を日本語で簡潔に説明してください。'},
          {
            inlineData: {
              mimeType: 'image/png',
              data: base64,
            },
          },
        ],
      },
    ],
  });

  console.log(res.text);
}

第8章 埋め込み(embeddings)と類似検索

embedContentは、文章をベクトルに変換するAPIで、ベクトルデータベースと組み合わせて類似検索やRAG（検索拡張生成）を構築する際の基盤となります。
outputDimensionalityで次元数を指定できるため、小さな次元でストレージ・計算負荷を抑えたり、大きな次元で精度を優先したりと、用途に応じて調整可能です。

// src/embedding.ts
import {GoogleGenAI} from '@google/genai';
import {EMBEDDING_MODEL} from './modelConfig';

const client = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY!});

export async function createEmbedding(text: string) {
  const res = await client.models.embedContent({
    model: EMBEDDING_MODEL,
    contents: text,
    config: {outputDimensionality: 128},
  });

  const vector = res.embeddings.values;
  console.log('vector length:', vector.length);
  return vector;
}

第9章 トークン数とコスト管理（countTokens, usageMetadata）

大きなプロンプトや履歴を扱うときは、トークン数を事前・事後に確認しておくと、エラーの防止やコストの可視化に役立ちます。
Gen AI SDKはcountTokensによる事前見積りと、レスポンスのusageMetadataに含まれる入力・出力トークン数を提供しているため、ログやメトリクスに記録してモニタリングが可能です。

// src/tokenUsage.ts
import {GoogleGenAI} from '@google/genai';
import {TEXT_MODEL} from './modelConfig';

const client = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY!});

export async function estimateTokens(prompt: string) {
  const count = await client.models.countTokens({
    model: TEXT_MODEL,
    contents: prompt,
  });
  console.log('Estimated tokens:', count.totalTokens);

  const res = await client.models.generateContent({
    model: TEXT_MODEL,
    contents: prompt,
  });
  console.log('Usage:', res.usageMetadata);
}

第10章 関数呼び出し（ツール呼び出し）による拡張

Geminiのツール呼び出し機能は、モデルが定義された関数を自動的に選択し、必要な引数を推論した上でコールする仕組みで、外部API連携や計算処理を自然言語から誘導できます。
SDK側では、関数のパラメータをJSONスキーマで宣言し、ツールコールのリクエストを受けて実際の関数を実行し、その結果を再度モデルに渡して最終回答を構築します。

// src/tools.ts（概念的な例）
import {GoogleGenAI} from '@google/genai';

const client = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY!});

const weatherTool = {
  functionDeclarations: [
    {
      name: 'getWeather',
      description: '指定された都市の現在の天気を返す',
      parameters: {
        type: 'object',
        properties: {city: {type: 'string'}},
        required: ['city'],
      },
    },
  ],
};

async function getWeather(city: string) {
  // 実際は外部天気APIを呼ぶ
  return `${city} は晴れで気温20度です。`;
}

第11章 Node.js + Express でのAPIサーバー統合

サーバー側でSDKを利用すると、APIキーを守りながら自前のRESTエンドポイントとしてGemini機能を公開できます。
Expressと組み合わせて/api/chatのようなルートを作れば、フロントエンドからは通常のHTTPリクエストを送るだけで、チャットボットや要約APIを利用可能になります。

// src/server.ts
import express from 'express';
import {GoogleGenAI} from '@google/genai';

const app = express();
app.use(express.json());

const client = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY!});

app.post('/api/chat', async (req, res) => {
  const {message} = req.body;

  const result = await client.models.generateContent({
    model: 'gemini-1.5-flash',
    contents: message,
  });

  res.json({reply: result.text});
});

app.listen(3000, () => {
  console.log('Server running at http://localhost:3000');
});

第12章 フロントエンドからの安全な利用パターン

ブラウザから直接SDKを使うとAPIキーが露出するため、本番環境ではサーバー側にSDKを置き、フロントエンドは自前APIを叩くアーキテクチャが推奨されます。
Next.jsなどでは、APIルートでGen AI SDKを呼び出し、そのエンドポイントをブラウザから使用することで、キーを守りつつリアルタイムなチャットや要約UIを構築できます。

// pages/index.tsx（Next.jsクライアント例）
import {useState} from 'react';

export default function Home() {
  const [input, setInput] = useState('');
  const [reply, setReply] = useState('');

  const send = async () => {
    const res = await fetch('/api/chat', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({message: input}),
    });
    const json = await res.json();
    setReply(json.reply);
  };

  return (
    <main>
      <textarea value={input} onChange={(e) => setInput(e.target.value)} />
      <button onClick={send}>送信</button>
      <pre>{reply}</pre>
    </main>
  );
}

第13章 エラー処理とリトライ戦略

実運用では、レート制限やタイムアウト、入力制約エラーなどが発生するため、SDK呼び出し部分に堅牢なエラー処理とリトライ戦略を組み込む必要があります。
指数バックオフ付きリトライや、エラーコードに応じた分岐（クライアントエラーは即失敗、サーバーエラーは数回リトライ）を実装しておくと、ユーザー体験を安定させられます。

// src/safeGenerate.ts
import {ai} from './config/genai';
import {TEXT_MODEL} from './modelConfig';

export async function safeGenerate(prompt: string) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      const res = await ai.models.generateContent({
        model: TEXT_MODEL,
        contents: prompt,
      });
      return res.text;
    } catch (err: any) {
      console.error(`Attempt ${attempt} failed:`, err.message);
      if (attempt === 3) throw err;
      await new Promise((r) => setTimeout(r, 500 * attempt));
    }
  }
}

第14章 Vertex AIとの統合とエンタープライズ利用

Gen AI SDKはVertex AIモードにも対応しており、vertexai: trueやproject, locationを指定すると、GCPのIAM・ネットワーク・ログ基盤と統合した形でGeminiを利用できます。
エンタープライズ環境では、VPC Service ControlsやCloud Loggingと組み合わせることで、社内ポリシーに沿ったアクセス制御や詳細監査を行いながら生成AIを業務システムへ組み込めます。

// src/vertexClient.ts
import {GoogleGenAI} from '@google/genai';

export const vertexClient = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT!,
  location: process.env.GOOGLE_CLOUD_LOCATION || 'us-central1',
});

第15章 学習リソースと今後の発展

Google Gen AI SDKとGemini APIは、テキスト生成・チャット・マルチモーダル・埋め込み・ツール呼び出しなど幅広い機能を持ちますが、基本的なgenerateContentパターンを一度覚えれば、少しずつ応用範囲を広げられます。
これからは公式ドキュメントやCookbook、コミュニティ記事を参考にしながら、プロンプト設計・評価方法・ログ分析を整備し、自分たちのアプリに最適な生成AIアーキテクチャを探っていくと良いでしょう。

// 最小構成のメインスクリプト例（@google/genaiのみ利用）
import {GoogleGenAI} from '@google/genai';

async function main() {
  const client = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY!});
  const res = await client.models.generateContent({
    model: 'gemini-2.0-flash',
    contents: '日本語で自己紹介文を書いてください。',
  });
  console.log(res.text);
}

main().catch(console.error);
1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?