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. RAG パターン
7. エラー処理
8. ベストプラクティス

---

1. クイックスタート

インストール

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

npm install @google/genai@^1.37.0

TypeScript プロジェクトの場合：

npm install -D typescript@^5.0.0

環境の設定

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

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

API キーはこちらから取得してください：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	最大の精度（デフォルト）	高	低速
128-3071	カスタム（範囲内の任意の値）	可変	可変

デフォルト：3072 次元 推奨：最適なパフォーマンスを得るには 768、1536、または 3072

コンテキストウィンドウ

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

レート制限

ティア	RPM	TPM	RPD	要件
無料	100	30,000	1,000	課金アカウント不要
ティア 1	3,000	1,000,000	-	課金アカウントをリンク済み
ティア 2	5,000	5,000,000	-	250 ドル以上の利用、30 日間の待機
ティア 3	10,000	10,000,000	-	1,000 ドル以上の利用、30 日間の待機

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

出力形式

{
  embedding: {
    values: number[] // Array of floating-point numbers
  }
}

---

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' }
});

const embedding: number[] = response.embedding.values;
const dimensions: number = embedding.length; // 3072 by default

正規化の要件

⚠️ 重要：3072 以外の次元数を使用する場合、類似度を計算する前に埋め込みを必ず正規化してください。API によって事前に正規化されるのは、3072 次元の埋め込みのみです。

重要な理由：正規化されていない埋め込みは大きさが一定ではないため、コサイン類似度の計算が歪み、検索結果が不正確になります。

正規化ヘルパー関数：

/**
 * Normalize embedding vector for accurate similarity calculations.
 * REQUIRED for dimensions other than 3072.
 *
 * @param vector - Embedding values from API response
 * @returns Normalized vector (unit length)
 */
function normalize(vector: number[]): number[] {
  const magnitude = Math.sqrt(
    vector.reduce((sum, val) => sum + val * val, 0)
  );
  return vector.map(val => val / magnitude);
}

// Usage with 768 or 1536 dimensions
const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: {
    taskType: 'RETRIEVAL_QUERY',
    outputDimensionality: 768  // NOT 3072
  }
});

// ❌ WRONG - Use raw values directly
const embedding = response.embedding.values;
await vectorize.insert([{ id, values: embedding }]);

// ✅ CORRECT - Normalize first
const normalized = normalize(response.embedding.values);
await vectorize.insert([{ id, values: normalized }]);

出典：埋め込みの公式ドキュメント

---

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}`);
});

バッチ REST API（fetch）

batchEmbedContents エンドポイントを使用します。

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

const data = await response.json();
// data.embeddings: Array of {values: number[]}

バッチ API の既知の問題

⚠️ 順序に関するバグ（2025年12月）：バッチサイズが大きい場合（500件超）、Batch API で順序が保持されないことがあります。

• 症状：エントリ 328 が位置 628 に現れます（通知されずにデータが破損します）
• 影響：結果を入力テキストと確実に照合できません
• 回避策：小さいバッチ（100件未満）で処理するか、一意の ID を追加して順序を確認します
• ステータス：Google が認識し、内部バグとして登録済みです（P0 優先度）
• ソース：GitHub Issue #1207

⚠️ メモリ制限（2025年12月）：大きなバッチ（10k 件超の埋め込み）では、ERR_STRING_TOO_LONG のクラッシュが発生する場合があります。

• エラー：Cannot create a string longer than 0x1fffffe8 characters
• 原因：API レスポンスに過剰な空白が含まれています（上限は約 536MB）
• 回避策：1 バッチあたりのテキストを 5,000 件未満に制限します
• ソース：GitHub Issue #1205

⚠️ レート制限の異常（2026年1月）：クォータ内であっても、Batch API が 429 RESOURCE_EXHAUSTED を返す場合があります。

• ステータス：Google チームが調査中です
• 回避策：指数バックオフと再試行ロジックを実装します
• ソース：GitHub Issue #1264

レート制限に対応するチャンク分割

大規模なデータセットを処理する場合、レート制限内に収まるようリクエストをチャンクに分割します：

async function batchEmbedWithRateLimit(
  texts: string[],
  batchSize: number = 50, // REDUCED from 100 due to ordering bug
  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, 50);

パフォーマンスの最適化

ヒント：

1. 複数のテキストを埋め込む場合はバッチ API を使用します（複数のリクエストではなく、単一のリクエストで処理します）
2. 処理を高速化し、ストレージを節約するには、より低い次元数（768）を選択します
3. レート制限エラーに備えて指数バックオフを実装します
4. 埋め込みをキャッシュして、API の冗長な呼び出しを避けます

---

5. タスクタイプ

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

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

タスクタイプ	ユースケース	例
RETRIEVAL_QUERY	ユーザーの検索クエリ	「パンクしたタイヤを修理するには？」
RETRIEVAL_DOCUMENT	インデックス登録や検索の対象となるドキュメント	商品説明、記事
SEMANTIC_SIMILARITY	テキストの類似性の比較	重複検出、クラスタリング
CLASSIFICATION	テキストの分類	スパム検出、感情分析
CLUSTERING	類似したテキストのグループ化	トピックモデリング、コンテンツの整理
CODE_RETRIEVAL_QUERY	コード検索クエリ	「配列をソートする関数」
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
});

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

セマンティック検索：

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

ドキュメントのクラスタリング：

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

品質への影響

適切なタスクタイプを使用すると、検索品質が大幅に向上します：

// ❌ BAD: No task type specified
const embedding1 = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery
});

// ✅ GOOD: Task type specified
const embedding2 = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: userQuery,
  config: { taskType: 'RETRIEVAL_QUERY' }
});

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

---

6. RAG のパターン

RAG（検索拡張生成）は、ベクトル検索と LLM による生成を組み合わせ、独自のナレッジベースを使って質問に答える AI システムを構築します。

ドキュメント取り込みパイプライン

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

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

// Generate embeddings for chunks
async function embedChunks(chunks: string[]): Promise<number[][]> {
  const response = await ai.models.embedContent({
    model: 'gemini-embedding-001',
    contents: chunks,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // ← Documents for indexing
      outputDimensionality: 768 // ← Match Vectorize index dimensions
    }
  });

  return response.embeddings.map(e => e.values);
}

// Store in Cloudflare Vectorize
async function storeInVectorize(
  env: Env,
  chunks: string[],
  embeddings: number[][]
) {
  const vectors = chunks.map((chunk, i) => ({
    id: `doc-${Date.now()}-${i}`,
    values: embeddings[i],
    metadata: { text: chunk }
  }));

  await env.VECTORIZE.insert(vectors);
}

クエリのフロー（検索 + 生成）

async function ragQuery(env: Env, userQuery: string): Promise<string> {
  // 1. Embed user query
  const queryResponse = await ai.models.embedContent({
    model: 'gemini-embedding-001',
    content: userQuery,
    config: {
      taskType: 'RETRIEVAL_QUERY', // ← Query, not document
      outputDimensionality: 768
    }
  });

  const queryEmbedding = queryResponse.embedding.values;

  // 2. Search Vectorize for similar documents
  const results = await env.VECTORIZE.query(queryEmbedding, {
    topK: 5,
    returnMetadata: true
  });

  // 3. Extract context from top results
  const context = results.matches
    .map(match => match.metadata.text)
    .join('\n\n');

  // 4. Generate response with context
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: `Context:\n${context}\n\nQuestion: ${userQuery}\n\nAnswer based on the context above:`
  });

  return response.text;
}

Cloudflare Vectorize との統合

Vectorize インデックスの作成（Gemini 用の 768 次元）：

npx wrangler vectorize create gemini-embeddings --dimensions 768 --metric cosine

wrangler.jsonc でのバインド：

{
  "name": "my-rag-app",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-25",
  "vectorize": {
    "bindings": [
      {
        "binding": "VECTORIZE",
        "index_name": "gemini-embeddings"
      }
    ]
  }
}

RAG Worker の全体例：

完全な実装については、templates/rag-with-vectorize.ts を参照してください。

---

7. エラー処理

よくあるエラー

1. API キーがない、または無効

// ❌ Error: API key not set
const ai = new GoogleGenAI({});

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

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

2. 次元数の不一致

// ❌ Error: Embedding has 3072 dims, Vectorize expects 768
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text
  // No outputDimensionality specified → defaults to 3072
});

await env.VECTORIZE.insert([{
  id: '1',
  values: embedding.embedding.values // 3072 dims, but index is 768!
}]);

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

3. レート制限

// ❌ Error: 429 Too Many Requests
for (let i = 0; i < 1000; i++) {
  await ai.models.embedContent({ /* ... */ }); // Exceeds 100 RPM on free tier
}

// ✅ Correct: Implement rate limiting
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' }
      });
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

8 件のエラーと詳細な解決方法については、references/top-errors.md を参照してください。

既知の問題を防ぐ

このセクションでは、上記の基本的なエラーに加えて、本番環境での使用中に見つかった問題を説明します。

Issue #9：3072 以外の次元では正規化が必要

エラー：類似度スコアが不正になりますが、エラーは発生しません 出典：公式の Embeddings ドキュメント 原因：API によって事前に正規化されるのは、3072 次元の埋め込みのみです。それ以外の次元（128～3071）では大きさが一定せず、コサイン類似度が歪みます。 防止策：3072 以外の次元を使用する場合は、必ず埋め込みを正規化してください。

function normalize(vector: number[]): number[] {
  const magnitude = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
  return vector.map(val => val / magnitude);
}

// When using 768 or 1536 dimensions
const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { outputDimensionality: 768 }
});

const normalized = normalize(response.embedding.values);
// Now safe for similarity calculations

Issue #10：Batch API の順序に関するバグ

エラー：データが気付かないうちに破損します。埋め込みが誤った順序で返されます 出典：GitHub Issue #1207 原因：Batch API は、バッチサイズが大きい場合（テキストが 500 件を超える場合）に順序を維持しません。例：エントリー 328 が位置 628 に現れます。 防止策：小さなバッチ（テキスト 100 件未満）で処理するか、順序を確認できるよう一意の識別子を追加してください。

// Safer approach with verification
const taggedTexts = texts.map((text, i) => `[ID:${i}] ${text}`);
const response = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  contents: taggedTexts,
  config: { taskType: 'RETRIEVAL_DOCUMENT', outputDimensionality: 768 }
});

// Verify ordering by parsing IDs if needed

Issue #11：Batch API のメモリ上限

エラー：Cannot create a string longer than 0x1fffffe8 characters 出典：GitHub Issue #1205 原因：Batch API の応答に過剰な空白文字が含まれるため、大きなペイロード（埋め込みが 10,000 件を超える場合）では応答サイズが Node.js の文字列上限（約 536MB）を超えます。 防止策：1 回のリクエストにつき、バッチをテキスト 5,000 件未満に制限してください。

// Safe batch size
async function batchEmbedSafe(texts: string[]) {
  const maxBatchSize = 5000;
  if (texts.length > maxBatchSize) {
    throw new Error(`Batch too large: ${texts.length} texts (max: ${maxBatchSize})`);
  }
  // Process batch...
}

Issue #12：LangChain の次元パラメーターが無視される（コミュニティからの情報）

エラー：次元数が一致しません。指定した 768 次元ではなく、3072 次元になります 出典：Medium の記事 確認状況：コミュニティから複数の報告あり 原因：LangChain の GoogleGenerativeAIEmbeddings クラスでは、コンストラクターに渡された output_dimensionality パラメーターが（Python SDK で）暗黙に無視されます。 防止策：次元パラメーターはコンストラクターではなく、embed_documents() メソッドに渡してください。JavaScript のユーザーは、新しい @google/genai SDK で同様の動作がないことを確認してください。

# ❌ WRONG - parameter silently ignored
embeddings = GoogleGenerativeAIEmbeddings(
    model="gemini-embedding-001",
    output_dimensionality=768  # IGNORED!
)

# ✅ CORRECT - pass to method
embeddings = GoogleGenerativeAIEmbeddings(model="gemini-embedding-001")
result = embeddings.embed_documents(["text"], output_dimensionality=768)

Issue #13：単一のリクエストでも Batch エンドポイントが使用される（コミュニティからの情報）

エラー：単一テキストの埋め込みで、想定より早くレート制限に達します 出典：GitHub Issue #427（Python SDK） 確認状況：googleapis 組織における公式 Issue 原因：embed_content() 関数は、単一テキストの場合でも内部で batchEmbedContents エンドポイントを呼び出します。そのため、レート制限の消費が増えます（Batch エンドポイントには異なる制限があります）。 防止策：単一の埋め込みリクエスト間に遅延を設け、429 エラーに対する指数バックオフを実装してください。

// Add delays to avoid rate limits
async function embedWithDelay(text: string, delayMs: number = 100) {
  const response = await ai.models.embedContent({
    model: 'gemini-embedding-001',
    content: text,
    config: { taskType: 'SEMANTIC_SIMILARITY' }
  });
  await new Promise(resolve => setTimeout(resolve, delayMs));
  return response.embedding.values;
}

---

8. ベストプラクティス

必ず行うこと

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

// Task type optimizes embeddings for your use case
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text,
  config: { taskType: 'RETRIEVAL_QUERY' } // ← Always specify
});

✅ 次元数を Vectorize に合わせる

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

✅ レート制限を実装する

// Use exponential backoff for 429 errors
async function embedWithBackoff(text: string) {
  // Implementation from Error Handling section
}

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

// Cache embeddings to avoid redundant API calls
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' }
  });

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

✅ 複数のテキストには Batch 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' }
});

絶対に行わないこと

❌ タスクタイプを省略しない

// Reduces quality by 10-30%
const embedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text
  // Missing taskType!
});

❌ 異なる次元数を混在させない

// Can't compare embeddings with different dimensions
const emb1 = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text1,
  config: { outputDimensionality: 768 }
});

const emb2 = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: text2,
  config: { outputDimensionality: 1536 } // Different dimensions!
});

// ❌ Can't calculate similarity between different dimensions
const similarity = cosineSimilarity(emb1.embedding.values, emb2.embedding.values);

❌ RAG に誤ったタスクタイプを使用しない

// Reduces search quality
const queryEmbedding = await ai.models.embedContent({
  model: 'gemini-embedding-001',
  content: query,
  config: { taskType: 'RETRIEVAL_DOCUMENT' } // Wrong! Should be RETRIEVAL_QUERY
});

---

同梱リソースの使用

テンプレート（templates/）

• package.json - 検証済みのバージョンを含むパッケージ設定
• basic-embeddings.ts - SDK を使った単一テキストの埋め込み
• embeddings-fetch.ts - Cloudflare Workers 向けの Fetch ベースの実装
• batch-embeddings.ts - レート制限付きのバッチ処理
• rag-with-vectorize.ts - Vectorize を使った完全な RAG 実装

リファレンス（references/）

• model-comparison.md - Gemini、OpenAI、Workers AI の埋め込みを比較
• vectorize-integration.md - Cloudflare Vectorize のセットアップとパターン
• rag-patterns.md - RAG の完全な実装戦略
• dimension-guide.md - 適切な次元数の選び方（768 vs 1536 vs 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％ 防止したエラー: 解決策を含む 13 件のエラーを記録（基本 8 件＋既知の問題 5 件） 本番環境でのテスト: ✅ RAG アプリケーションで検証済み パッケージバージョン: @google/[email protected] 最終更新日: 2026-01-21 変更点: 正規化の要件、バッチ API に関する警告（順序の不具合、メモリ制限、レート制限の異常）、LangChain との互換性に関する注意事項を追加

---

ライセンス

MIT ライセンス - 個人および商用プロジェクトで自由に利用できます。

---

ご質問や問題がありますか？

• GitHub: https://github.com/jezweb/claude-skills
• メール: [email protected]