📖
Generative Language API (Gemini) の簡易まとめ

2024/09/02に公開
 はじめにGoogleが提供する Generative Language API (Gemini) のエンドポイントを簡易的にまとめてみました。順番やグループを変えている点ご了承ください。
https://ai.google.dev/api/all-methods?hl=ja

 (0) Model
 list - モデル一覧を取得するGET /v1beta/models

 get - モデル詳細を取得するGET /v1beta/models/{model}

 (1) Content
 generateContent - コンテンツを生成するPOST /v1beta/models/{model}:generateContent

Contents (テキストや画像、音声、動画、PDFなど) を添付してリクエストする。
補足SystemInstruction (システム命令) として、出力形式や対象読者レベルなどの定義ができる。

CachedContent (キャッシュ済みコンテンツ) を利用してリクエストすることもできる。
SafetySettings (安全でないコンテンツをブロックする設定) を指定できる。

ToolsやToolConfig (外部システム連携の実行ルール) を指定できる。

GenerationConfig (生成や出力のルール) を一部のモデルで指定できる。
ファイル各画像は258個のトークンに相当。

Gemini 1.5 Pro と 1.5 Flash は、最大3,600個の画像ファイルをサポートしている。
音声は1秒を25個のトークン。1分間の音声は1,500トークン。

最大長は9.5時間で、英語の音声の回答のみを推測できる。

 generateContent - コンテンツを生成する (チューニング済みモデル)POST /v1beta/tunedModels/{tunedModel}:generateContent

「Tuning」で作成するチューニング済みモデルを利用してコンテンツを生成する。

 streamGenerateContent - コンテンツを生成する (ストリーミング形式)POST /v1beta/models/{model}:streamGenerateContent

generateContentは生成完了してからレスポンスを返すが、このstreamGenerateContentを使用すると部分的に順次レスポンスを返す。やり取りの迅速化を図れる。

 startChat / sendMessage - インタラクティブなチャットを行うNode.js / Python / Go (RESTではありません)

複数の質問をまとめて回答してくれる仕組み。

 countTokens - トークン数を取得するPOST /v1beta/models/{model}:countTokens

リクエストのトークン数、レスポンスのトークン数、それらの合計トークン数を取得できる。
補足Gemini 1.5 Flash は 100万トークンのコンテキストウィンドウ
Gemini 1.5 Pro   は 200万トークンのコンテキストウィンドウ
100万トークンの例
50,000行のコード（1行あたり80文字として）
過去5年間に送信したすべてのテキストメッセージ
平均的な英語の小説 8冊
平均的な長さのポッドキャスト エピソードの文字起こしが200件以上

 (2) File基本的にはコンテンツを生成する時に、都度ファイルを添付してリクエストすることができる。

一方で何度も添付したいファイルは、このAPIでストレージに保存すると再利用しやすいです。

生成APIを利用する前に先にファイルをアップロードすることで、ユーザー体験も良くなりそうです。

 upload - ファイルを作成するPOST /v1beta/files

 get - ファイル一覧を取得するGET /v1beta/files

 list - ファイル詳細を取得するGET /v1beta/files/{file}

 delete - ファイルを削除するDELETE /v1beta/files/{file}

 (3) Cacheリクエスト時に何度も参照したいコンテンツをキャッシュする仕組み。

トークン数や保存期間に基づいて課金されるが、費用の削減と速度の向上につながる可能性もある。

(例) 長時間の動画ファイル、大規模なドキュメントを繰り返し分析する等

 create - キャッシュを作成するPOST /v1beta/cachedContents

 list - キャッシュ一覧を取得するGET /v1beta/cachedContents

 get - キャッシュ詳細を取得するGET /v1beta/cachedContents/{content}

nameやmodel等のメタデータを取得するもの。(保存されたコンテンツの取得や表示はできない)

 patch - キャッシュを更新する (有効期限のみ)PATCH /v1beta/cachedContents/{content}

キャッシュ有効期限はデフォルトで1時間。「expireTime (Timestamp)」か「ttlSeconds (Duration)」 を指定して、変更することが出来る。

 delete - キャッシュを削除するDELETE /v1beta/cachedContents/{content}

 (4.0) Tuningトレーニングデータを用意してチューニングしたモデルを作成することができる。

20個のサンプルが必要で、ケースごとに推奨されるサンプルデータ数は違う。

(例) 分類なら100以上、ドキュメント検索なら100以上、要約なら100〜500以上
補足詳細設定としてエポック、バッチサイズ、学習率、学習率の乗数を指定することもできる。

詳細なファインチューニングのチュートリアル

詳細なファインチューニングの概要

 create - チューニング済みモデルを作成するPOST /v1beta/tunedModels

 list - チューニング済みモデル一覧を取得するGET /v1beta/tunedModels

 get - チューニング済みモデル詳細を取得するGET /v1beta/tunedModels/{tunedModel}

 patch - チューニング済みモデルを更新するPATCH /v1beta/tunedModels/{tunedModel}

 delete - チューニング済みモデルを削除するDELETE /v1beta/tunedModels/{tunedModel}

 transferOwnership - チューニング済みモデルの所有権を譲渡するPOST /v1beta/tunedModels/{tunedModel}:transferOwnership

 (4.1) Tuning - Permission
 create - チューニング済みモデルの権限を作成するPOST /v1beta/tunedModels/{tunedModel}/permissions

 list - チューニング済みモデルの権限一覧を取得するGET /v1beta/tunedModels/{tunedModel}/permissions

 get - チューニング済みモデルの権限詳細を取得するGET /v1beta/tunedModels/{tunedModel}/permissions/{permission}

 patch - チューニング済みモデルの権限を更新するPATCH /v1beta/tunedModels/{tunedModel}/permissions/{permission}

 delete - チューニング済みモデルの権限を削除するDELETE /v1beta/tunedModels/{tunedModel}/permissions/{permission}

 (5.0) Semantic Retrievalハルシネーション(事実とは異なる情報を利用して回答すること)をおこさせないために、コーパスを用意することでLLMの知識を補強することができる。

(NotebookLMのようなイメージ)
補足「コーパス (Corpora)」とはテキストの集合体/データベースを意味し、その中に複数の「ドキュメント (Document)」がある。さらに細分化して「チャンク (Chunk)」とすることもできる。

大きなドキュメントを小さな断片またはチャンクに分割することで、検索時のコンテンツの関連性を改善することができる。

 generateAnswer - 根拠のある回答を生成するPOST /v1beta/models/{model}:generateAnswer

ハルシネーションを最小限に抑えながら、特定のコンテキストに基づいた回答のみを返す。
補足「answerable_probability」という回答可能性をもとに「その質問に回答できるか/できないか」を判定する。個々のユースケースによって異なるが、0.5以下の値が開始しきい値として推奨されている。

 (5.1) Semantic Retrieval - Corporaプロジェクトには最大5つのコーパスを含めることができる。

 create - コーパスを作成するPOST /v1beta/corpora

 list - コーパス一覧を取得するGET /v1beta/corpora

 get - コーパス詳細を取得するGET /v1beta/corpora/{corpora}

 query - コーパスに対してセマンティック検索を行うPOST /v1beta/corpora/{corpora}:query

セマンティック検索を行い、関連する文章を取得できる。chunkやdocumentのメタデータに対して、ANDやORなどの条件を追加して検索できる。
指定出来るfilterの例metadata_filter = [
  {
    key = "document.custom_metadata.year"
    conditions = [
      {int_value = 2020, operation = GREATER_EQUAL},
      {int_value = 2010, operation = LESS}
    ]
  },
  {
    key = "document.custom_metadata.genre"
    conditions = [
      {string_value = "drama", operation = EQUAL},
      {string_value = "action", operation = EQUAL}
    ]
  }
]

 patch - コーパスを更新するPATCH /v1beta/corpora/{corpora}

 delete - コーパスを削除するDELETE /v1beta/corpora/{corpora}

 (5.2) Semantic Retrieval - Corpora - Documentコーパスには最大10,000個のドキュメントを含めることができる。

 create - コーパスのドキュメントを作成するPOST /v1beta/corpora/{corpora}/documents

 list - コーパスのドキュメント一覧を取得するGET /v1beta/corpora/{corpora}/documents

 get - コーパスのドキュメント詳細を取得するGET /v1beta/corpora/{corpora}/documents/{document}

 query - コーパスのドキュメントに対してセマンティック検索を行うPOST /v1beta/corpora/{corpora}/documents/{document}:query

指定したドキュメントに絞って、その中でセマンティック検索を行う。

 patch - コーパスのドキュメントを更新するPATCH /v1beta/corpora/{corpora}/documents/{document}

 delete - コーパスのドキュメントを削除するDELETE /v1beta/corpora/{corpora}/documents/{document}

 (5.3) Semantic Retrieval - Corpora - Chunkコーパスには最大100万個のチャンクを含めることができる。

チャンクには最大2,043個のトークンを含めることができる。

 create - コーパスのドキュメントのチャンクを作成するPOST /v1beta/corpora/{corpora}/documents/{document}/chunks

 batchCreate - コーパスのドキュメントのチャンクを一括作成するPOST /v1beta/corpora/{corpora}/documents/{document}/chunks:batchCreate

 list - コーパスのドキュメントのチャンク一覧を取得するGET /v1beta/corpora/{corpora}/documents/{document}/chunks

 get - コーパスのドキュメントのチャンク詳細を取得するGET /v1beta/corpora/{corpora}/documents/{document}/chunks/{chunk}

 patch - コーパスのドキュメントのチャンクを更新するPATCH /v1beta/corpora/{corpora}/documents/{document}/chunks/{chunk}

 batchUpdate - コーパスのドキュメントのチャンクを一括更新するPOST /v1beta/corpora/{corpora}/documents/{document}/chunks:batchUpdate

 delete - コーパスのドキュメントのチャンクを削除するDELETE /v1beta/corpora/{corpora}/documents/{document}/chunks/{chunk}

 batchDelete - コーパスのドキュメントのチャンクを一括削除するPOST /v1beta/corpora/{corpora}/documents/{document}/chunks:batchDelete

 (5.4) Semantic Retrieval - Corpora - Permission
 create - コーパスの権限を作成するPOST /v1beta/corpora/{corpora}/permissions

 list - コーパスの権限一覧を取得するGET /v1beta/corpora/{corpora}/permissions

 get - コーパスの権限詳細を取得するGET /v1beta/corpora/{corpora}/permissions/{permission}

 patch - コーパスの権限を更新するPATCH /v1beta/corpora/{corpora}/permissions/{permission}

 delete - コーパスの権限を削除するDELETE /v1beta/corpora/{corpora}/permissions/{permission}

 (6) Embeddingテキストを数値座標(ベクトル)に変換することができる。そうするとデータベースのデータをクラスタリングしたり、文字の類似度をもとにドキュメント検索ができるようになる。
補足エンベディングの概要

クラスタリング

ドキュメント検索

 embedContent - エンベディングベクトルを生成するPOST /v1beta/models/{model}:embedContent

 batchEmbedContents - 複数のエンベディングベクトルを生成するPOST /v1beta/models/{model}:batchEmbedContents

 (7) PaLM [非推奨]!PaLM API は廃止されています。Vertex AI PaLM API は、2024年10月に廃止される予定です。

 generateText - レスポンスを生成する [非推奨]POST /v1beta/models/{model}:generateText

 generateText - レスポンスを生成する (チューニング済みモデル) [非推奨]POST /v1beta/tunedModels/{tunedModel}:generateText

 countTextTokens - トークン数を取得する [非推奨]POST /v1beta/models/{model}:countTextTokens

 embedText - エンベディングベクトルを生成する [非推奨]POST /v1beta/models/{model}:embedText

 batchEmbedText - 複数のエンベディングベクトルを生成する [非推奨]POST /v1beta/models/{model}:batchEmbedText

 generateMessage - レスポンスを生成する [非推奨]POST /v1beta/models/{model}:generateMessage

 countMessageTokens - トークン数を取得する [非推奨]POST /v1beta/models/{model}:countMessageTokens

 (8) その他
 JSON mode
指定したJSONの形式を返してもらえるようにする仕組み。
generateContent などのAPIを利用する時に、下記のように generationConfig の responseMimeType を指定することでJSONで返すようにできる。
generationConfig の responseSchema を指定することで、どのような形式のJSONで出力するかも自在に変更できる。
generationConfigの例generationConfig: {
  responseMimeType: "application/json",
  responseSchema: {
    type: SchemaType.ARRAY,
    items: {
      type: SchemaType.OBJECT,
      properties: {
        recipe_name: {
          type: SchemaType.STRING,
        },
      },
    },
  },
}

 Function Calling
自作の関数を呼び出してくれるようにしてくれる仕組み。
generateContent などのAPIを利用する時に、tools の function_declarations に呼び出せる関数を定義する。リクエスト内容をもとに最適な引数の値を代入し、関数を呼んだ結果をもとにレスポンスを返してくれる。
(例) 「映画名と地域を引数として映画館を検索する関数」を用意する。受け取ったリクエスト内容から「映画名」と「地域」の値をもとに映画館を検索し、「映画館の名前」と「住所」をレスポンスで返してくれる。
関数は複数リクエストに添付することができ、必須の引数を指定することもできる。
「注文の送信」や「データベースの更新」などもできるが、重大な結果をもたらすような関数の呼び出しは、事前にユーザーに確認することが推奨されている。

 Code Extension
コードを実行してコンテンツを生成する仕組み。
generateContent などのAPIを利用する時に、tools の codeExecution を指定することで利用できる。
(例) 回答生成内で「方程式を解く」というコードを実行し、その結果をレスポンスで返してくれる。