Knowledge Base API の使用を開始

Knowledge Base API がコンテンツをどのように整理し、文書を処理し、AI 操作を実行するかを理解して、プラットフォームに対応するアプリケーションを作成できるようになります。

この API は、コレクションと文書の管理、コンテンツの処理、および質問の回答、要約、検索、構造化抽出などの AI 機能の適用に関するワークフローをサポートします。このページでこれらの要素がどのように連携するかを理解してから、エンドポイントレベルの実装の詳細については API リファレンスを使用してください。

はじめる前に

次の項目について確認してください。

• Knowledge Base へのアクセス権。
• アプリケーション用に設定された API アクセス権。
• コレクションへのアクセス権またはコレクションを作成する権限。
• 現在のエンドポイント定義とスキーマに関して利用可能な Knowledge Base API リファレンス。

API アクセスを設定していない場合は、Knowledge Base API アクセスの設定を参照してください。

API の仕組み

一般的な Knowledge Base API ワークフローは次のシーケンスに従います。

認証 → コレクション → 文書 → インデックス → 推論 → 応答

コレクション

コレクションは、アプリケーションが操作するナレッジドメインを定義します。コレクションを作成すると、回答にはその固有の名前空間が含まれ、後続の操作で使用します。

次に例を示します。

{
"namespace": "<collection-namespace>",
"name": "example-collection"
}

文書と推論リクエストのためにコレクションの名前空間を保持してください。

文書

文書はコレクションにアップロードされ、固有の文書識別子が割り当てられます。

アップロード回答は文書を識別するため、アプリケーションは処理をトラッキングし、後のリクエストでそれを参照できます。

{
"document_id": "<document-id>",
"document_name": "example.pdf"
}

インデックスの作成

文書のアップロードとインデックス作成は別々のステージです。

アップロードはファイルを Knowledge Base に移行します。インデックス作成はコンテンツを抽出し、AI の操作で使用するためにそのコンテンツを処理します。

文書に対する推論リクエストを送信する前に、アプリケーションは処理が完了したことを確認する必要があります。

推論

推論操作は、処理されたコンテンツに Knowledge Base の AI 機能を適用します。

次の機能を利用できます。

• 質問への回答
• 文書の要約
• コンテキスト検索
• 構造化プロパティ抽出

API リファレンスを使用して、実行する操作のエンドポイントとリクエストスキーマを決定します。

返答

推論回答は生成結果を返し、関連するアトリビューション情報を含めることができます。

操作によっては、アトリビューションデータで結果に関連付けられているソースコンテンツ、ページ、座標を識別できます。その情報をユーザーにどのように表示するかはアプリケーションが決定します。

基本的な API ワークフローの実行

最も簡単なアプリケーションワークフローは、コレクションを作成し、文書を追加し、処理を待機し、推論操作を実行することです。

文書処理について

文書のライフサイクルは、アプリケーションがアップロードされた内容をいつ使用できるかに影響します。

この区別は、自動化されたワークフローにとって特に重要です。アプリケーションは、アップロード後すぐに推論リクエストを送信せずに、処理ステータスを確認する必要があります。

推論操作を選択

アプリケーションがソースコンテンツで実行することに基づいて操作を選択します。

質問への回答

Q&A を使用して、コレクションまたは文書の内容について自然な言葉で質問します。

API は、ストリーミングと非ストリーミングの両方の Q&A を提供します。

Streaming Q&A は、生成される際に回答を段階的に返します。インターフェイスで生成されるコンテンツを段階的に表示する場合に使用します。

Streaming Q&A では、カスタム指示をリクエストに適用するかどうかを指定することもできます。ストリーミング Q&A 回答で推論を生成するかどうかもコントロールできます。

非ストリーミング Q&A は、生成が完了するまで待機し、完成した回答を返します。アプリケーションが部分的な出力を表示する必要がない場合に使用します。

要約

要約を使用して、文書コンテンツの簡潔な表現を生成します。

API リファレンスでは、現在のリクエスト要件とサポートされている入力を定義しています。

コンテキスト検索

コンテキスト検索を使用して、指定された検索テキストに関連するコンテンツを取得します。

これにより、アプリケーションは会話型の回答を生成することなく、関連するソースの資料を識別できます。

プロパティの抽出

アプリケーションが文書コンテンツから構造化された値を必要とする場合は、抽出を使用します。

抽出定義では、次のような情報を識別できます。

プロパティ名: contract_value
タイプ: 整数
説明: 本契約の契約値
プロンプト: ドル単位で最大の契約値を抽出します。

返される結果には、抽出された値、信頼度情報、およびソースアトリビューションを含めることができます。

操作で使用されるコンテンツを制御する

API では、リクエストに参加するコンテンツを決定するいくつかの方法が提供されています。

コレクションと文書

コレクションと文書識別子を使用して、操作で使用可能な優先コンテンツを定義します。

文書タグ

タグはコレクションではなく文書に関連付けられています。

文書タグは Knowledge Base API を通じてのみ利用可能で、標準ユーザーインターフェイスでは表示されません。

サポートされている操作でタグを使用して、リクエストで検討される文書をフィルタリングできます。たとえば、アプリケーションで文書のグループを財務文書としてタグ付けし、そのタグを持つ文書に質問を制限することができます。

添付ファイル

添付ファイルはコレクション文書とは区別されます。

会話に添付ファイルを追加しても、そのファイルがコレクションに追加されるわけではありません。添付ファイルは、コレクションのコンテンツとチャット履歴とともに、生成された回答にコンテキストを提供できます。

コレクションに永続的にコンテンツを追加することなく、一時的に、または特定の会話でそのコンテンツを使用する場合は、添付ファイルのエンドポイントを使用します。

アトリビューションデータを扱う

推論回答には、生成された出力を裏付けるソースコンテンツに接続するアトリビューション情報を含めることができます。

アトリビューションデータには次の情報を含めることができます。

• 補足テキスト
• 文書情報
• ページ番号
• ページ座標

API はこの情報をデータとして提供します。これらの情報の表示方法は、アプリケーション側で決定する必要があります。

例えば、アプリケーションは返された座標を使用して、生成された回答の根拠となるソース文書内の箇所をハイライト表示する機能を構築できます。

アクセスとリクエストの失敗を処理する

API 操作は、認証されたアイデンティティが利用できる権限を使用します。

認証済み ID がリクエストされたコレクション、文書、または操作へのアクセス権限がない場合、リクエストが失敗する可能性があります。

トラブルシューティング手順

• 返された HTTP ステータスと回答を確認します。
• 認証済み ID がリクエストされたリソースにアクセスできることを確認します。
• 推論を実行する前に、文書の処理が正常に完了したことを確認します。
• リクエストで提供された識別子が正しいことを確認します。
• 回答ヘッダーで返された X-Request-ID を取得します。

X-Request-ID は Knowledge Base サービス全体でリクエストを識別するもので、サポートが失敗したリクエストを調査する際に役立ちます。

実装の検討事項

• 単一のアップロードリクエストは、最大 200 個のファイルをサポートします。追加ファイルは後続のリクエストでアップロードできます。
• アップロードとインデックス作成は別の操作です。
• 文書は推論に使用される前に、完了した処理ステータスにになる必要があります。
• 添付ファイルは独立したリソースであり、コレクションに自動的に追加されません。
• タグは文書に属し、サポートされた操作でソースコンテンツをフィルタリングするために使用できます。
• 現在のエンドポイント、パラメーター、スキーマ、およびサポートされている操作には、API リファレンスを信頼できるソースとして使用します。

開発を続ける

アプリケーションでこれらの概念を実演する実用的な例が必要な場合は、Python デモを使用してください。

Knowledge Base Python デモの使用を開始

特定の操作を実装する準備ができたら、API リファレンスを使用してください。

Knowledge Base API リファレンスを開く