OpenAI API - ChatのRequest/Response内容。(TypeScript-Interface)

IChatMessage.ts

/**
 * Chat形式でやり取りするメッセージの型。
 * Docs: https://platform.openai.com/docs/api-reference/chat/create
 */
export interface IChatMessage {
  /**
   * 話者の役割。
   * `system`、`user`、`assistant`のどれかを指定。
   * - `system`: どんな返答をしてもらうかを指定するのに使用。
   * - `user`: 質問を行うユーザーのこと。
   * - `assistant`: 解答の補助情報
   * - `tool`: 外部API
   *
   * 例:
   * ```json
   * {"role": "system", "content": "You are a helpful assistant."},
   * {"role": "user", "content": "Who won the world series in 2020?"},
   * {"role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020."},
   * {"role": "user", "content": "Where was it played?"}
   * ```
   */
  role: "system" | "user" | "assistant" | "tool";
  /**
   * 指定内容。
   */
  content: string | IApiChat_Message_Content[];
  /**
   * 会話者のラベル。
   * これを使えば同じ`role`でも、`SystemUser1`, `SystemUser2`の様に話者を変えることが可能。
   * 空白を含めるのは不可。
   */
  name?: string;
  /**
   * `role`=`assistant`の時のみ使用可能。
   * 外部APIを呼び出し、回答情報への補足情報として使ってもらうことが可能。
   * 詳細: https://platform.openai.com/docs/guides/function-calling
   * 具体的なユースケース: https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models
   */
  tool_calls?: {
    /**
     * 外部API呼び出しラベル。
     * 値はこちらで定義できる。
     */
    id: string;
    /**
     * ツール種別、執筆当時(2024/05)は`function`のみ許可。
     */
    type: "function";
    /**
     * モデルに呼び出してもらう関数の定義。
     */
    function: {
      /**
       * 呼び出す関数識別子。
       */
      name: string;
      /**
       * 関数の説明。モデルがどの様な関数かどうかを識別するために使う。
       */
      description?: string;
      /**
       * これ以降関数の引数等を記載可能、詳細は[ユースケース](https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models)を参照に。
       */
    };
  }[];
  /**
   * `role`=`tool`の時のみ使用可能。(この時は当プロパティは必須となる)
   * このメッセージが応答する外部API呼び出しID。
   */
  tool_call_id?: string;
}

/**
 * 指定内容。
 */
export interface IChatMessage_Content {
  /**
   * 種別。
   * - `text`: テキスト
   * - `image_url`: 画像(URL形式で指定)
   */
  type: "text" | "image_url";
  /**
   * `type`=`text`の場合に指定。
   * テキスト内容。
   */
  text?: string;
  /**
   * `type`=`image_url`の場合に指定。
   * 添付画像内容。
   */
  image_url?: {
    /**
     * 添付対象の画像URL。
     * Base64エンコードして画像をData URI化しても送付可能。
     */
    url: string;
    /**
     * 解像度を指定できる。デフォルトは`auto`。
     * - `low`: 画像の低解像度(512px x 512px)verを受け取り、85トークンで画像を認識
     * - `high`: 最初にモデルが低解像度の画像を確認し、入力画像のサイズに基づいて入力画像の詳細な切り抜きを作成して検証
     */
    detail?: "low" | "high" | "auto";
  };
}

IChatRequest.ts

import {
  IChatMessage
} from "./IChatMessage";

/**
 * 会話応答を取得するAPIのPOSTリクエスト。
 * Docs: https://platform.openai.com/docs/api-reference/chat/create
 */
export interface IChatRequest {
  /**
   * 使用する言語エンジン。
   */
  model: string;
  /**
   * 入力内容。
   */
  messages: IChatMessage[];
  /**
   * ランダムさ。
   * 0~2まで指定可能、低い(0.2)と確定的な応答に、高い(0.8)と想像的な応答になる。
   * デフォルト値は`1`。
   * `temperature`と`top_p`を両方変更することは非推奨。
   */
  temperature?: number;
  /**
   * nucleusサンプリング。
   * 0.1は、上位10％の確率を持つトークンのみを考慮、というのを意味する。
   * `temperature`と`top_p`を両方変更することは非推奨。
   * デフォルト値は`1`。
   */
  top_p?: number;
  /**
   * 生成する応答パターン数、デフォルト値は`1`。
   * 応答パターン毎に出力トークンが増大するため、公式Docsに依れば`1`以上にするのは非推奨。
   */
  n?: number;
  /**
   * 認識されるMAXトークン数。トークン数の数によって従量課金されるので、調整しておくと無難かも。
   * 指定するプロンプトがどの程度のトークン数とみなされるかは[こちら](https://platform.openai.com/tokenizer)を参照に。
   */
  max_tokens?: number;
  /**
   * 生成したトークンに基づいて、新しいトークンに課すペナルティ。
   * 同じトークンの繰り返し可能性を減らしてくれ、新しいトピックに対して応答しやすくしてくれる。
   * `-2.0`~`2.0`まで指定可能。
   * デフォルト値は`0`。
   */
  presence_penalty?: number;
  /**
   * 生成したテキストに基づいて、新しいトークンに課すペナルティ。
   * 同じテキスト出力の可能性を減らしてくれる。
   * `-2.0`~`2.0`まで指定可能。
   * デフォルト値は`0`。
   * 詳しくは: https://platform.openai.com/docs/guides/text-generation/parameter-details
   */
  frequency_penalty?: number;
  /**
   * ※ベータ版の機能。
   * 指定されると、同じ`seed`の値であれば同じ様な返答を返す様にしてくれる。(確実性はない)
   * 同じ返答が返ってくるかはバックエンド構成にもよるため、レスポンス>`system_fingerprint`でバックエンド構成を参照しながら検証すること。
   * 詳しくは[こちら](https://platform.openai.com/docs/guides/text-generation/reproducible-outputs)
   */
  seed?: number;
  /**
   * 指定したトークンが出現する可能性を減らしてくれる。
   * デフォルト値は`null`。
   * 詳しくは[こちら](https://platform.openai.com/docs/api-reference/chat/create#chat-create-logit_bias)。
   */
  logit_bias?: object;
  /**
   * トークンの生成を停止する文章、最大4つまで指定可能。
   * 例: `stop`=`天気`と指定した場合、モデルが「今日の天気は晴れです」と返そうとしても「今日の」までしか返さない。
   * (この時のレスポンス>`finish_reason`は`stop`となる)
   * デフォルト値は`null`。
   */
  stop?: string | string[];
  /**
   * 進行状況をChatGPTと同様にストリーミングバックするかどうか。
   * デフォルト値は`false`。
   */
  stream?: boolean;
  /**
   * 指定する際は、`stream`=`true`にする必要あり。
   * ストリーミングオプション。
   */
  stream_options?: {
    /**
     * `true`にすると、`data: [DONE]`の前に追加のストリーミング(全体のトークン使用量が記載)がチャンクされる。
     */
    include_usage: boolean;
  };
  /**
   * `true`指定で、各トークンのログ確率を返却。
   * ログ確率をざっくり言うと: そのトークンがどういう経緯で生成されたかが記載される。
   * 「次のトークンにはこの値が来たかもしれない」と言う値まで見ることが出来る。
   */
  logprobs?: boolean;
  /**
   * 指定する際は、`logprobs`=`true`にする必要あり。
   * 「次のトークンにはこの値が来たかもしれない」と言う候補を何件出すかを指定可能。
   * 値は`0`〜`20`まで指定可能。
   */
  top_logprobs?: number;

  /**
   * `GPT-4 Turbo`, `GPT-3.5 Turbo`で指定可能。(恐らく`GPT-4o`もOK)。
   * 指定すると、生成結果が有効なJSONオブジェクトであることを保証してくれる様になる。
   * ※使用時は、`messages`の内容もJSONオブジェクトにする必要がある。
   * ※レスポンス>`finish_reason`=`length`の場合、JSONオブジェクトが途中でぶつ切りになり有効な物にならない可能性がある。
   */
  response_format?: { type: "json_object" };
  /**
   * 外部APIを呼び出し、回答情報への補足情報として使ってもらうことが可能。
   * 詳細: https://platform.openai.com/docs/guides/function-calling
   * 具体的なユースケース: https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models
   */
  tools?: {
    /**
     * ツール種別、執筆当時(2024/05)は`function`のみ許可。
     */
    type: "function";
    /**
     * モデルに呼び出してもらう関数の定義。
     */
    function: {
      /**
       * 呼び出す関数識別子。
       */
      name: string;
      /**
       * 関数の説明。モデルがどの様な関数かどうかを識別するために使う。
       */
      description?: string;
      /**
       * これ以降関数の引数等を記載可能、詳細は[ユースケース](https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models)を参照に。
       */
    };
  }[];
  /**
   * モデルが`tools`で指定した外部APIを使用するかどうかを制御可能。
   * - `none`: 外部APIを使用しない(`tools`指定無し時のデフォルト)
   * - `auto`: 使うか使わないかはモデルにお任せ(`tools`指定有り時のデフォルト)
   * - `required`:外部APIを必ず使用してもらう
   * - `{"type": "function", "function": {"name": "my_function"}}`: 指定した`name`の外部APIを使うことを強制
   */
  tool_choice?:
    | "none"
    | "auto"
    | "required"
    | {
        type: "function";
        function: {
          /**
           * 指定対象の外部API名。
           */
          name: string;
        };
      };
  /**
   * OpenAI上のユーザー識別子。
   * 任意の文字列を送付でき、送付しておけばOpenAIアプリケーションでポリシー違反が検出された場合に、より実用的なフィードバックを提供してくれるみたい。
   * 識別情報を送信しない様に、ユーザーID等である場合はハッシュ化することを推奨。
   * 詳しくは[こちら](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)参照。
   */
  user: string;
}

IChatResponse.ts

import {
  IChatMessage
} from "./IChatMessage";

/**
 * 会話応答を取得するAPIのPOSTレスポンス。
 * ※ストリーミングでは返答内容が異なるが、割愛。
 * Docs: https://platform.openai.com/docs/api-reference/chat/create
 */
export interface IApiChatResponse {
  /**
   * 応答ID。
   */
  id: string;
  /**
   * ChatAPIが選んだ回答内容。
   * リクエスト>`n`が2以上の場合、複数の回答が返ってくる。
   */
  choices: IChatResponse_Choice[];
  /**
   * 返却日時。
   * UNIXタイムスタンプ形式で返却。
   */
  created: number;
  /**
   * 返答に使用したモデル。
   */
  model: string;
  /**
   * モデルが実行されたバックエンド構成の識別子。
   * リクエスト>`seed`パラメータと合わせ、同じ様な回答が返ってくるかのどうかの検証に使える。
   */
  system_fingerprint: string;
  /**
   * トークン使用状況。
   */
  usage: IUsage;
  /**
   * 対象が何のカテゴリかを示す。
   * 当該だと「会話応答を取得するAPI」なので、必ず`chat.completion`が返ってくる…はず。
   */
  object: "chat.completion";
}

/**
 * ChatAPIが選んだ回答内容。
 */
export interface IApiChatResponse_Choice {
  /**
   * 回答内容の順番。
   * `0`からスタート。
   */
  index: number;
  /**
   * 回答内容。
   */
  message: IChatMessage[];
  /**
   * 回答が終了した理由が記載される。
   * - `length`: 長さ不足、この回答が来たら`max_tokens`数を増やす方がいい。
   * - `stop`: ChatGPTが十分な確信を持って会話を終えれると判断してもらえた。(リクエストの`stop`へ語句を指定した結果の場合も、これになる)
   * - `content_filter`: コンテンツポリシーにより省略された。
   * - `tool_calls`: モデルがツールを呼び出した。
   */
  finish_reason: "stop" | "length" | "content_filter" | "tool_calls";
  /**
   * トークンがどの様な過程を経て決定されたかどうかがみれる。
   */
  logprobs: {
    content: {
          /**
           * 対象トークン。
           */
          token: string;
          /**
           * 対象トークンが上位20位以内にある場合のログ確率。
           * ※値`-9999.0`は、トークンの可能性が非常に低いことを示す。
           */
          logprob: number;
          /**
           * トークンのUTF-8表現を表す整数リスト。
           * 内容が複数のトークンで表され、それらのバイト表現を組み合わせて正しいテキスト表現を生成する必要がある場合に役立つ。
           * トークンのバイト表現がない場合は、`null`になることも。
           */
          bytes: number[];
          /**
           * 当該トークンの他にも選択される可能性が高かったトークン一覧。
           * リクエスト>`top_logprobs`の値によって一覧に出てくる数が変わる。
           */
          top_logprobs: IChatResponse_Choice_Logprobs[];
        }[];
  };
}

export interface IChatResponse_Choice_Logprobs {
  /**
   * 対象トークン。
   */
  token: string;
  /**
   * 対象トークンが上位20位以内にある場合のログ確率。
   * ※値`-9999.0`は、トークンの可能性が非常に低いことを示す。
   */
  logprob: number;
  /**
   * トークンのUTF-8表現を表す整数リスト。
   * 内容が複数のトークンで表され、それらのバイト表現を組み合わせて正しいテキスト表現を生成する必要がある場合に役立つ。
   * トークンのバイト表現がない場合は、`null`になることも。
   */
  bytes: number[];
}

/**
 * OpenAI APIのトークン使用状況。
 */
export interface IUsage {
  /**
   * 返答内容のトークン数。
   */
  completion_tokens: number;
  /**
   * プロンプトのトークン数。
   */
  prompt_tokens: number;
  /**
   * 合計トークン数。
   * このトークン数で課金額が決まる。
   */
  total_tokens: number;
}