API活用

Prev Next

Classic/VPC環境で利用できます。

エクスプローラー メニューで提供する APIについて説明します。

リランカー API

リランカー APIは、検索したドキュメントとクエリ間の関連性を評価して関連性の高いドキュメントを選択し、その結果を要約・圧縮して RAG回答を作成します。検索結果の一部を補正する際に活用でき、検索したすべてのドキュメントを回答作成に使用するのではなく、選別したドキュメントのみを使用できるため、効率的にリソースを運用できます。

RAG Reasoning API

RAG回答は信頼性を高めるための手段として、引用出典、引用元インデックス表記などの回答タイプを備えています。これらの回答タイプに合わせて学習された RAG Reasoningモデルを活用することで、ユーザーに根拠に基づいた RAG回答を提供できます。RAG Reasoningは Function calling形式のエンジン呼び出しを提供します。単一または複数の RAG関数を指定でき、LLMが状況に合わせて自律的に最適な関数を選択して検索拡張生成タスクを行います。

RAG Reasoning APIは独自でも検索拡張生成に活用できますが、リランカー APIとチェーニングして使用することで、より安定的にマルチターン、マルチクエリリクエストをサポートする RAG回答システムを提供できます。

chain_rag_reranker.png

トークン計算機 API

トークン計算機 APIとは、入力した文章のトークン数を計算できます。トークン計算機を活用して最適なトークン数を見つけたり、効率的なプロンプトを作成できます。
トークン計算機(チャット)、トークン計算機(チャット v3)は、HyperCLOVA Xモデルを利用できる Chat Completionsと Chat Completions v3 APIで入力した文章のトークン数を計算する APIです。
トークン計算機(エンベディング v2)とは、エンベディング v2 APIの bge-m3モデルで入力した文章のトークン数を計算する APIです。

スライディングウィンドウ API

スライディングウィンドウ APIは、チャットモードでプロンプトと結果値を HyperCLOVA X言語モデルが処理できる最大トークン数以内に調整し、会話が途切れることなく行えるようにします。

チャットモードでは、ユーザーとアシスタントの会話が HyperCLOVA X言語モデルが処理できる最大トークン数を超えると、これ以上新しい会話を作成できないように設定されています。スライディングウィンドウ APIは、ユーザーとアシスタントの会話履歴の中で最も古い会話ターンを削除することで、会話が作成されなくなる状況を防ぐことができます。会話を削除する場合、システム指示文の次の会話、つまり最初に入力された会話のターンから順に削除します。

注意
  • ユーザーとアシスタント間の会話履歴を会話ターン単位で前から順次削除するため、新しく作成される会話内容が以前の会話内容を反映できない場合があります。
  • 特に結果値の最大作成トークン数(APIの maxTokens値)が大きく設定されている場合、それに比例して会話履歴が削除されるため、新しく作成される会話内容が以前の会話履歴を十分に反映できない場合があります。
参考
  • スライディングウィンドウ APIは Chat Completions API対応モデルに対してのみ動作し、Chat Completions v3 API対応モデルに対しては動作しません。
  • スライディングウィンドウ APIの結果値がそのまま Chat Completions APIに入力されるように順序を設定する必要があります。
  • モデル名、maxTokensなどの他の設定値は、一緒に使用する Chat Completions APIの設定値と同じく設定する必要があります。

スライディングウィンドウの動作方式

入力された会話履歴の総トークン数(A)と新しく作成される会話の最大作成トークン数(B=maxTokens)の合計が、モデルの処理可能な最大トークン数(X)より大きい場合(つまり、A+B>X)、Chat Completions APIはこれ以上会話を作成しません。この問題を解決するために、スライディングウィンドウ APIは超過したトークン数(A+B-X)だけ既存の会話のうち古い会話ターンから削除します。会話ターンから一部だけ削除されないように、会話ターン単位で削除します(超過トークン数以上の最小会話ターンを削除)。
例えば、下図のように超過したトークン数が200トークンである場合、スライディングウィンドウ APIを適用すると、既存の会話履歴のうち最も古い2つの会話ターン(100、200トークン)を削除します。超過したトークン数が100トークン以下の場合、既存の会話履歴のうち最も古い1つの会話ターンのみ削除されます。つまり、ユーザーとアシスタント間の会話ペアではなく、個々の会話ターンが削除されます。
clovastudio-explorer_slidingwindow_ko.png

スライディングウィンドウのタスクプロセス

スライディングウィンドウ APIを適用すると、全体の会話内容のトークン数を別途調整する必要なく、Chat Completions APIを連続的に使用することができます。

スライディングウィンドウ APIのタスクプロセスは、次の通りです。

  1. Chat Completions APIを使用する前に、スライディングウィンドウ APIを先に呼び出して入力したいプロンプト(会話内容; messages)をリクエストに入力します。
  2. スライディングウィンドウ APIのレスポンス内の結果値(messages)をそのまま Chat Completions APIリクエストに入力します。
  3. モデル名と最大トークン数は、Chat Completion APIとスライディングウィンドウ APIに同じく入力します。

サマリー API

要約 APIは、与えられた文章を段落に分けた後、各段落を要約できる APIです。

要約 APIは長文を文脈に合わせて段落分けし、それぞれの段落を要約できます。重要な情報を維持しながら、不要な部分を削除してテキストの長さを短くすることができます。段落分けの segMaxSizeと segMinSizeを用いて1つの段落の中に含む文字数を制限し、要約文の分量も調整できます。

clovastudio-explorer03_summarize_ko

要約 APIは以下のように活用できます。

  • 長文の議事録を要約でき、議事録の内容を把握して重要な内容を要約して作成できます。
  • 長文のメール内容からも重要な内容を要約して簡単に把握できます。
  • レポートやスクリプトを簡単に要約できます。文脈に合わせて段落分けして要約するため、簡単に目次を作成できます。

エンベディング API

入力テキストを数値形式のベクトル値に変換できます。ユーザーのタスクと目的に応じて、3つのモデルの中から希望する方式を選択できます。各モデルは、同じ文章ペアに対して異なる類似度結果を返します。新規ユーザーの場合、トークン計算機 APIをサポートするエンベディング v2の使用をお勧めします。

ツール名 モデル 最大トークン数 ベクトルディメンション 推奨距離指標 (distance metric) 備考
エンベディング clir-emb-dolphin 500トークン 1024 IPアドレス(Inner/Dot/Scalar Product; 内的) トークン計算機をサポートしない
エンベディング clir-sts-dolphin 500トークン 1024 Cosine Similarity(コサイン類似度) トークン計算機をサポートしない
エンベディング v2 bge-m3 8192トークン 1024 Cosine Similarity(コサイン類似度)
  • トークン計算機をサポート
  • オープンソースモデル

エンベディング APIのモデル別の特徴は、次の通りです。
clovastudio-explorer_embedding1_ko.png

参考

エンベディング v2の出力をオープンソースで提供される bge-m3モデル出力と同様に得るためには、次をご参照ください。

  • エンベディング v2は bge-m3モデルの計3つの方法(sparse、dense、multi-dense/colbert)出力のうち、denseに該当する値を返します。
  • エンベディング v2は FP16と正規化(normalization)が適用されていません。

エンベディング APIのタスクプロセス

一般的なエンベディングのタスクプロセスは、データ準備、エンベディング実行、ベクトル結果の保存、そして API開発と結果呼び出しで構成されます。このプロセスでエンベディングされた結果を保存し、データベースに活用できます。

エンベディングのタスクプロセスは、次の通りです。
clovastudio-explorer_embedding2_ko.png

  1. エンベディングするファイルを Textに変換します。
  2. テキストのタイプと目的に応じて、段落分けまたは要約 APIを利用して Textを適切に区切ります。
  3. 適切なエンベディングモデルを選択した後、Textをベクトルに変換してエンベディングタスクを行います。
  4. エンベディングされた結果とソース Textをベクトル DBに一緒に保存します。
  5. ユーザーの入力クエリをベクトル変換して API化 → DBに保存されたベクトルとの類似度を比較して一致するベクトルを探し、マッピングされたソーステキストを呼び出して最終結果を作成します。
  6. APIの結果を promptに入れ、ユーザーが望む適切な形式のレスポンスを作成し、最終結果を出力するために Chat Completions APIを使用できます。

エンベディングの活用

エンベディング APIは以下のように活用できます。

  • 文章間のベクトル類似度を計算して検索機能を改善できます。例えば、ユーザーが入力した検索キーワードとドキュメントのベクトル類似度を測定し、最も関連性の高いドキュメントを返すことができます。
  • 2つの文章間の類似度を計算して関連ドキュメントの類似性を判断したり、文章間の意味的類似性を比較できます。
  • 類似の特性を持つドキュメントをクラスタにグループ化できます。
  • ドキュメントを分類できます。ベクトル化されたテキストデータを学習されたモデルに使用し、テキストのテーマや感情に応じて分類するなど、様々な分類タスクに活用できます。

長いテキストの処理

エンベディング APIが一度に処理できる最大テキストの長さは500トークン(clir-emb-dolphin, clir-sts-dolphin)または8192トークン(v2=bge-m3)です。テキストのトークン制限によりエンベディングが難しい場合、長いテキストを適切に分割するためにチャンク方式を使用することをお勧めします。テキストを分割するときは正しい情報を抽出するために、テキストを意味単位で適切に分割することが重要です。チャンクはテキストを小片に分割するタスクで、基本テキスト分割/段落分け/要約があります。

チャンク方式の種類と各方式のメリットとデメリットは、次の通りです。

方式 説明 メリット デメリット
基本テキスト分割 テキストを一定の長さの単位で分割する方式 テキストを細かく分けてクエリに対する答えを抽出しやすい テキストを意味単位ではなく長さ単位で分割するため、テキストの先頭と末尾の処理が不十分であり、テキスト全体の意味把握が難しい
段落 テキストを文脈に合わせて意味のある段落に分離 テキストが意味のある単位にまとめられ、エンベディングのパフォーマンスが向上 長い段落の場合、クエリに対する答えがある領域を特定しにくい
要約 重要な内容に焦点を当てて、長いテキストを短く要約 段落分けよりも長い文脈のテキストを要約でき、ドキュメント単位でエンベディングしやすい 長い段落の場合、クエリに対する答えがある領域を特定しにくい
参考

CLOVA Studioではトークン計算機(エンベディング v2) API、段落分け API、要約 APIを提供します。詳細情報は、トークン計算機 API、段落分け API、要約 APIをご参照ください。

bge-m3モデルの引用情報は次の通りです。

@misc{bge-m3,
    title={BGE M3-Embedding: Multi-Lingual, Multi-Functionality, Multi-Granularity Text Embeddings Through Self-Knowledge Distillation},
    author={Jianlv Chen and Shitao Xiao and Peitian Zhang and Kun Luo and Defu Lian and Zheng Liu},
    year={2024},
    eprint={2402.03216},
    archivePrefix={arXiv},
    primaryClass={cs.CL}
}

段落分け API

段落分け APIは、文章間の類似度を計算してトピック単位で段落を区切ります。1つの段落の中に入ることができるトークンの数を指定でき、段落に空行がない場合や区切りが明確でない場合でも、文脈を把握して段落を分割することができます。段落の分割数は segCnt 設定値で調整できます。自動的に段落分けしたい場合は、 segCnt 値を-1に設定します。値が0以上の場合は、ユーザーが入力した値だけ段落分けを行います。

段落分け APIのタスクプロセスは、次の通りです。

clovastudio-explorer03_segment_ko