google-gemini-embeddings

Google Gemini Embeddings

Google Gemini embeddings API の本番環境対応ガイド

このスキルでは、テキスト埋め込みの生成に使用する gemini-embedding-001 モデルについて、SDK の使い方、REST API のパターン、バッチ処理、Cloudflare Vectorize を使った RAG 統合、セマンティック検索やドキュメントのクラスタリングといった高度なユースケースまで、包括的に解説します。

---

目次

1. クイックスタート
2. gemini-embedding-001 モデル
3. 基本的な埋め込み
4. バッチ埋め込み
5. タスクタイプ
6. よくあるエラー 5 選
7. ベストプラクティス
8. リファレンスを読み込むタイミング

---

1. クイックスタート

インストール

Google Generative AI SDK をインストールします。

bun add @google/genai@^1.27.0

TypeScript プロジェクトの場合：

bun add -d typescript@^5.0.0

環境の設定

Gemini API キーを環境変数として設定します。

export GEMINI_API_KEY="your-api-key-here"

API キーは次の URL から取得できます：https://aistudio.google.com/apikey

最初の埋め込みの例

import { GoogleGenAI } from "@google/genai";

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

const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: 'What is the meaning of life?',
  config: {
    taskType: 'RETRIEVAL_QUERY',
    outputDimensionality: 768
  }
});

console.log(response.embedding.values); // [0.012, -0.034, ...]
console.log(response.embedding.values.length); // 768

結果：テキストの意味を表す 768 次元の埋め込みベクトルです。

---

2. gemini-embedding-001 モデル

モデルの仕様

現行モデル：gemini-embedding-001（安定版、本番環境対応）

• ステータス：安定版
• 試験運用版：gemini-embedding-exp-03-07（2025 年 10 月に非推奨。使用しないでください）

次元数

このモデルは、Matryoshka Representation Learning を使用して、出力の次元数を柔軟に設定できます。

次元数	ユースケース	ストレージ	パフォーマンス
768	ほとんどのユースケースに推奨	低	高速
1536	精度と効率のバランス	中	中
3072	最高精度（デフォルト）	高	低速

デフォルト：3072 次元
推奨：ほとんどの RAG アプリケーションでは 768 次元

次元数ごとのストレージコストや精度のトレードオフ、次元数の移行方法を詳しく比較する場合は、references/dimension-guide.md を読み込んでください。

Gemini embeddings と OpenAI（text-embedding-3-small/large）または Cloudflare Workers AI（BGE）を比較する場合は、references/model-comparison.md を読み込んでください。

レート制限

ティア	RPM	TPM	RPD
無料	100	30,000	1,000
ティア 1	3,000	1,000,000	-

RPM = 1 分あたりのリクエスト数、TPM = 1 分あたりのトークン数、RPD = 1 日あたりのリクエスト数

コンテキストウィンドウ

• 入力上限：テキストあたり 2,048 トークン
• 入力タイプ：テキストのみ（画像、音声、動画は不可）

---

3. 基本的な埋め込み

SDK の使用方法（Node.js）

単一テキストの埋め込み：

import { GoogleGenAI } from "@google/genai";

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

const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: 'The quick brown fox jumps over the lazy dog',
  config: {
    taskType: 'SEMANTIC_SIMILARITY',
    outputDimensionality: 768
  }
});

console.log(response.embedding.values);
// [0.00388, -0.00762, 0.01543, ...]

Fetch の使用方法（Cloudflare Workers）

SDK をサポートしていない Workers／エッジ環境向け：

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const apiKey = env.GEMINI_API_KEY;
    const text = "What is the meaning of life?";

    const response = await fetch(
      'https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent',
      {
        method: 'POST',
        headers: {
          'x-goog-api-key': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          content: {
            parts: [{ text }]
          },
          taskType: 'RETRIEVAL_QUERY',
          outputDimensionality: 768
        })
      }
    );

    const data = await response.json();

    // Response format:
    // {
    //   embedding: {
    //     values: [0.012, -0.034, ...]
    //   }
    // }

    return new Response(JSON.stringify(data), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

レスポンスの解析

interface EmbeddingResponse {
  embedding: {
    values: number[];
  };
}

const response: EmbeddingResponse = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: 'Sample text',
  config: { taskType: 'SEMANTIC_SIMILARITY', outputDimensionality: 768 }
});

const embedding: number[] = response.embedding.values;
const dimensions: number = embedding.length; // 768

---

4. バッチ埋め込み

1 回のリクエストで複数のテキストを処理（SDK）

複数のテキストの埋め込みを同時に生成します。

import { GoogleGenAI } from "@google/genai";

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

const texts = [
  "What is the meaning of life?",
  "How does photosynthesis work?",
  "Tell me about the history of the internet."
];

const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts, // Array of strings
  config: {
    taskType: 'RETRIEVAL_DOCUMENT',
    outputDimensionality: 768
  }
});

// Process each embedding
response.embeddings.forEach((embedding, index) => {
  console.log(`Text ${index}: ${texts[index]}`);
  console.log(`Embedding: ${embedding.values.slice(0, 5)}...`);
  console.log(`Dimensions: ${embedding.values.length}`);
});

レート制限に合わせたチャンク分割

大規模なデータセットを処理する場合は、リクエストをチャンクに分割してレート制限を超えないようにします。

async function batchEmbedWithRateLimit(
  texts: string[],
  batchSize: number = 100, // Free tier: 100 RPM
  delayMs: number = 60000 // 1 minute delay between batches
): Promise<number[][]> {
  const allEmbeddings: number[][] = [];

  for (let i = 0; i < texts.length; i += batchSize) {
    const batch = texts.slice(i, i + batchSize);

    console.log(`Processing batch ${i / batchSize + 1} (${batch.length} texts)`);

    const response = await ai.models.embedContent({
      model: 'gemini-embedding-001',
      contents: batch,
      config: {
        taskType: 'RETRIEVAL_DOCUMENT',
        outputDimensionality: 768
      }
    });

    allEmbeddings.push(...response.embeddings.map(e => e.values));

    // Wait before next batch (except last batch)
    if (i + batchSize < texts.length) {
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }

  return allEmbeddings;
}

// Usage
const embeddings = await batchEmbedWithRateLimit(documents, 100);

---

5. タスクタイプ

taskType パラメーターを使うと、特定のユースケースに合わせて埋め込みを最適化できます。最良の結果を得るには、必ずタスクタイプを指定してください。

利用可能なタスクタイプ（全 8 種類）

タスクタイプ	ユースケース	例
RETRIEVAL_QUERY	ユーザーの検索クエリ	"How do I fix a flat tire?"
RETRIEVAL_DOCUMENT	インデックス化・検索するドキュメント	商品の説明、記事
SEMANTIC_SIMILARITY	テキストの類似性の比較	重複の検出、クラスタリング
CLASSIFICATION	テキストの分類	スパム検出、感情分析
CLUSTERING	類似したテキストのグループ化	トピックモデリング、コンテンツの整理
CODE_RETRIEVAL_QUERY	コード検索クエリ	"function to sort array"
QUESTION_ANSWERING	回答を求める質問	FAQ の照合
FACT_VERIFICATION	根拠に基づく主張の検証	ファクトチェックシステム

RAG システム（最も一般的）

// When embedding user queries
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: {
    taskType: 'RETRIEVAL_QUERY', // ← Use RETRIEVAL_QUERY
    outputDimensionality: 768
  }
});

// When embedding documents for indexing
const docEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: documentText,
  config: {
    taskType: 'RETRIEVAL_DOCUMENT', // ← Use RETRIEVAL_DOCUMENT
    outputDimensionality: 768
  }
});

影響：適切なタスクタイプを使用すると、検索の関連性が10～30％向上します。

---

6. よくあるエラー上位5件

エラー1：次元の不一致

エラー：Vector dimensions do not match. Expected 768, got 3072

原因：outputDimensionality パラメーターを指定していません（デフォルトは3072です）。

修正方法：

// ❌ BAD: No outputDimensionality (defaults to 3072)
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text
});

// ✅ GOOD: Match Vectorize index dimensions
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { outputDimensionality: 768 } // ← Match your index
});

エラー2：レート制限（429 Too Many Requests）

エラー：429 Too Many Requests - Rate limit exceeded

原因：1分あたり100件のリクエスト数を超えています（無料プラン）。

修正方法：

// ✅ GOOD: Exponential backoff
async function embedWithRetry(text: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await ai.models.embedContent({
        model: 'gemini-embedding-001',
        content: text,
        config: { taskType: 'SEMANTIC_SIMILARITY', outputDimensionality: 768 }
      });
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

エラー3：テキストの切り捨て（通知なし）

エラー：エラーは発生しません。テキストは2,048トークンで通知なしに切り捨てられます。

原因：入力テキストが2,048トークンの上限を超えています。

修正方法：長いテキストは埋め込み処理の前に分割します。

function chunkText(text: string, maxTokens = 2000): string[] {
  const words = text.split(/\s+/);
  const chunks: string[] = [];
  let currentChunk: string[] = [];

  for (const word of words) {
    currentChunk.push(word);

    // Rough estimate: 1 token ≈ 0.75 words
    if (currentChunk.length * 0.75 >= maxTokens) {
      chunks.push(currentChunk.join(' '));
      currentChunk = [];
    }
  }

  if (currentChunk.length > 0) {
    chunks.push(currentChunk.join(' '));
  }

  return chunks;
}

エラー4：誤ったタスクタイプ

エラー：エラーは発生しませんが、検索品質が低下します（10～30％悪化）。

原因：誤ったタスクタイプを使用しています（例：クエリに RETRIEVAL_DOCUMENT を使用）。

修正方法：

// ❌ BAD: Wrong task type for RAG query
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_DOCUMENT' } // ← Wrong!
});

// ✅ GOOD: Correct task types
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_QUERY', outputDimensionality: 768 }
});

エラー5：コサイン類似度の計算エラー

エラー：Similarity values out of range (-1.5 to 1.2)

原因：適切なコサイン類似度の計算式ではなく、内積を使用しています。

修正方法：

// ✅ GOOD: Proper cosine similarity
function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) {
    throw new Error('Vector dimensions must match');
  }

  let dotProduct = 0;
  let magnitudeA = 0;
  let magnitudeB = 0;

  for (let i = 0; i < a.length; i++) {
    dotProduct += a[i] * b[i];
    magnitudeA += a[i] * a[i];
    magnitudeB += b[i] * b[i];
  }

  if (magnitudeA === 0 || magnitudeB === 0) {
    return 0; // Handle zero vectors
  }

  return dotProduct / (Math.sqrt(magnitudeA) * Math.sqrt(magnitudeB));
}

詳細な解決方法とともに、バッチサイズの上限、ベクトルストレージでの精度損失、モデルバージョンの混同を含む8件すべてのエラーについては、references/top-errors.md を読み込んでください。

---

7. ベストプラクティス

必ず行うこと

✅ タスクタイプを指定する

const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { taskType: 'RETRIEVAL_QUERY' } // ← Always specify
});

✅ Vectorize と次元を一致させる

const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { outputDimensionality: 768 } // ← Match index
});

✅ レート制限を実装する

// Use exponential backoff for 429 errors (see Error 2)

✅ 埋め込みをキャッシュする

const cache = new Map<string, number[]>();

async function getCachedEmbedding(text: string): Promise<number[]> {
  if (cache.has(text)) {
    return cache.get(text)!;
  }

  const response = await ai.models.embedContent({
    model: 'gemini-embedding-001',
    content: text,
    config: { taskType: 'SEMANTIC_SIMILARITY', outputDimensionality: 768 }
  });

  const embedding = response.embedding.values;
  cache.set(text, embedding);
  return embedding;
}

✅ 複数のテキストにはバッチ API を使用する

// Single batch request vs multiple individual requests
const embeddings = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: texts, // Array of texts
  config: { taskType: 'RETRIEVAL_DOCUMENT', outputDimensionality: 768 }
});

絶対に行わないこと

❌ タスクタイプを省略しない - 品質が10～30％低下します ❌ 異なる次元を混在させない - 埋め込みを比較できません ❌ RAG に誤ったタスクタイプを使用しない - 検索品質が低下します ❌ 2,048トークンを超えない - テキストは通知なしに切り捨てられます ❌ レート制限を無視しない - 429エラーが発生します

---

8. リファレンスを読み込むタイミング

次の場合は references/rag-patterns.md を読み込みます：

• RAG（検索拡張生成）システムを構築する場合
• チャンク分割戦略を含むドキュメント取り込みパイプラインが必要な場合
• コサイン類似度を使ったセマンティック検索を実装する場合
• 履歴を使った会話型 RAG を構築する場合
• 引用付き RAG または複数クエリ RAG のパターンが必要な場合
• フィルター付き RAG、ストリーミング RAG、ハイブリッド検索の完全なサンプルが必要な場合
• K-means の実装を使ったドキュメントクラスタリングが必要な場合

次の場合は references/vectorize-integration.md を読み込みます：

• 埋め込み用に Cloudflare Vectorize インデックスを設定する場合
• Vectorize の挿入／クエリパターンを含む完全な RAG のサンプルが必要な場合
• Vectorize の次元／メトリクス設定を構成する場合
• メタデータのベストプラクティスを実装する場合
• Vectorize の次元不一致エラーをトラブルシューティングする場合
• インデックス管理コマンド（作成／削除／一覧表示）が必要な場合

次の場合は references/dimension-guide.md を読み込みます：

• 768、1536、3072の次元から選択する場合
• ストレージコストの分析（10万件と100万件のベクトル）が必要な場合
• 精度のトレードオフ（MTEB ベンチマーク）を理解する場合
• 異なる次元間で移行する場合
• クエリパフォーマンスを比較する場合
• 最適な次元を選択するためのテスト方法が必要な場合

次の場合は references/model-comparison.md を読み込みます：

• Gemini と OpenAI（text-embedding-3-small/large）を比較する場合
• Gemini と Cloudflare Workers AI（BGE）を比較する場合
• MTEB ベンチマークスコアが必要な場合
• 使用する埋め込みモデルを決定する場合
• OpenAI から Gemini に移行する場合
• プロバイダー間のコスト差を理解する場合

次の場合は references/top-errors.md を読み込みます：

• 記載されている8件のエラーのいずれかが発生した場合
• 詳細な根本原因の分析が必要な場合
• 本番環境で検証済みの解決方法とコード例が必要な場合
• 本番システム向けのエラー処理を構築する場合
• デプロイ前の確認チェックリストが必要な場合

---

同梱リソースの使用

テンプレート（templates/）

• package.json - 検証済みバージョンを含むパッケージ設定
• basic-embeddings.ts - SDK を使用した単一テキストの埋め込み
• embeddings-fetch.ts - Cloudflare Workers 向けの Fetch ベースの実装
• batch-embeddings.ts - レート制限付きのバッチ処理
• rag-with-vectorize.ts - Vectorize を使用した完全な RAG 実装
• semantic-search.ts - コサイン類似度と top-K 検索
• clustering.ts - K-means クラスタリングの実装

リファレンス（references/）

• model-comparison.md - Gemini、OpenAI、Workers AI の埋め込みを比較
• vectorize-integration.md - Cloudflare Vectorize のセットアップとパターン
• rag-patterns.md - RAG 実装の完全な戦略
• dimension-guide.md - 適切な次元数（768、1536、3072）の選び方
• top-errors.md - よくある 8 つのエラーと詳細な解決策

スクリプト（scripts/）

• check-versions.sh - @google/genai パッケージのバージョンが最新か確認

---

公式ドキュメント

• 埋め込みガイド: https://ai.google.dev/gemini-api/docs/embeddings
• モデル仕様: https://ai.google.dev/gemini-api/docs/models/gemini#gemini-embedding-001
• レート制限: https://ai.google.dev/gemini-api/docs/rate-limits
• SDK リファレンス: https://www.npmjs.com/package/@google/genai
• Context7 ライブラリ ID: /websites/ai_google_dev_gemini-api

---

関連スキル

• google-gemini-api - テキスト／画像生成向けの Gemini API メインスキル
• cloudflare-vectorize - 埋め込みを保存するためのベクトルデータベース
• cloudflare-workers-ai - Workers AI の埋め込み（BGE モデル）

---

成功指標

トークン削減量: 手動実装と比べて約 60％ 防止したエラー: 解決策付きで 8 件のエラーを記録 本番環境でのテスト: ✅ RAG アプリケーションで検証済み パッケージバージョン: @google/[email protected] 最終更新日: 2025-11-21

---

ライセンス

MIT License - 個人および商用プロジェクトで無料で利用できます。

---

ご質問や問題がある場合

• GitHub: https://github.com/secondsky/claude-skills
• Email: [email protected]