メインコンテンツまでスキップ

Knowledge Base

AIエージェントが参照する検索可能なContextを保存し、metadata schema、自動抽出、クエリ時フィルタリングで管理します。​

なぜKnowledge Baseを使うのか​

Knowledge Baseは、AIエージェントが質問に答える際に参照するContextを保存するもので、Agent Studioにおける Knowledge Base 能力と同じです。Contextを追加することで、基盤となるAIモデルには含まれていない可能性がある特定トピックについて、関連する回答を提供できるようになります。

以下はシンプルなコード例ですが、追加できるContextははるかに複雑にできます。良いContextの例として、コードドキュメント、製品マニュアル、業務運用（例: 営業時間）、ユーザー固有データなどのリソースがあります。Contextタイプを組み合わせてAIエージェントの堅牢なナレッジベースを作成し、ユーザーに必要な情報を提供できるようにできます。

Knowledge Baseの作成​

エージェントのContextを追加または更新するには、まずKnowledge Baseを作成して接続する必要があります。

最初に、標準で提供されているembedding modelを使って新しいKnowledge Baseを作成します。

Client code
await squid.ai().knowledgeBase('banking-knowledgebase').upsertKnowledgeBase({
  description: 'This Knowledge Base contains information on card data',
  embeddingModel: 'text-embedding-3-small',
  chatModel: 'gpt-5.5',
  metadataFields: [],
});

または、connector ID、モデル名、dimensionsを含むオブジェクトを渡すことで、integration-based embedding modelを使用できます。セットアップ手順は OpenAI Compatible Embedding connector を参照してください。

Client code
await squid
  .ai()
  .knowledgeBase('banking-knowledgebase')
  .upsertKnowledgeBase({
    description: 'This Knowledge Base contains information on card data',
    embeddingModel: {
      integrationId: 'my-embeddings',
      model: 'text-embedding-3-small',
      dimensions: 1536,
    },
    chatModel: 'gpt-5.5',
    metadataFields: [],
  });

ContextのUpsert​

Knowledge BaseにContextを追加するには、upsertContext() メソッドを使用し、Contextとそのtypeを渡します。

upsertContext() メソッドはcontext IDを受け取ります。context IDを指定すると、後で変更したいときにContextへアクセスしやすくなります。

Client code
const data = `Platinum Mastercard® Fair Credit, No annual fee. Flexible due dates...`;

await squid.ai().knowledgeBase('banking-knowledgebase').upsertContext({
  type: 'text',
  title: 'Credit Card Info',
  text: data,
  contextId: 'credit-cards',
});

または、upsertContexts() を使用してContext配列をupsertできます。

Client code
const creditCard1 = `Platinum Mastercard® Fair Credit, No annual fee. Flexible due dates...`;
const creditCard2 = `Gold Mastercard®, $50 annual fee. Due dates once a month...`;

await squid
  .ai()
  .knowledgeBase('banking-knowledgebase')
  .upsertContexts([
    {
      type: 'text',
      title: 'Credit Card 1 Info',
      text: creditCard1,
      contextId: 'credit-cards1',
    },
    {
      type: 'text',
      title: 'Credit Card 2 Info',
      text: creditCard2,
      contextId: 'credit-cards2',
    },
  ]);

エージェントへの接続​

Knowledge Baseは、エージェントに接続してはじめてそのエージェントの回答に影響します。Knowledge Baseを接続し、エージェントによる利用方法を設定するには、Knowledge Baseをエージェントに接続する を参照してください。

Contextタイプ​

Contextは text と file の2種類がサポートされています。

Text contextは、Contextを含む文字列で作成します。

Client code
const data = `Platinum Mastercard® Fair Credit, No annual fee. Flexible due dates...`;

await squid.ai().knowledgeBase('banking-knowledgebase').upsertContext({
  type: 'text',
  title: 'Credit Card Info',
  text: data,
  contextId: 'credit-cards',
});

File contextは、upsertContext() メソッドの第2引数として File オブジェクトを渡して作成します。ファイルはSquidにアップロードされ、その内容からContextが作成されます。

Client code
const file = new File([contextBlob], 'CreditCardList.pdf', { type: 'application/pdf' });

await squid.ai().knowledgeBase('banking-knowledgebase').upsertContext(
  {
    type: 'file',
    contextId: 'credit-cards',
  },
  file
);
Note

Contextは好きなだけ長くできますが、LLM promptには文字数制限があるため、実際にユーザーの問い合わせと一緒に含まれるのはContextの一部になる場合があります。promptを構築する際、Squidは提供されたContextのうち、ユーザーの質問に最も関連する部分を選択します。

Contextの取得​

すべてのContext一覧を取得するには、listContexts() メソッドを使用します。このメソッドは contextId を含むエージェントContextオブジェクトの配列を返します。

Client code
await squid.ai().knowledgeBase('banking-knowledgebase').listContexts();

特定のContext項目を取得するには、Context IDを渡して getContext() メソッドを使用します。

Client code
await squid.ai().knowledgeBase('banking-knowledgebase').getContext('credit-cards');

Contextの削除​

Contextエントリを削除するには、deleteContext() メソッドを使用します。

Client code
await squid.ai().knowledgeBase('banking-knowledgebase').deleteContext('credit-cards');

このメソッドは、指定したcontext IDに対応するエントリがまだ作成されていない場合にエラーになります。

Context Metadata​

AI knowledge baseのContextを追加または更新する際、任意でContext metadataを提供できます。Metadataはオブジェクトで、キーの値はstring、number、booleanの型を取れます。Metadataを追加するとContextに関する追加情報が提供され、エージェントとの対話時に利用できます。次の例は、PDFをContextとして追加し、2つのkey/valueペアをmetadataとして渡す例です。

Client code
const file = new File([contextBlob], 'CreditCardList.pdf', { type: 'application/pdf' });

await squid
  .ai()
  .knowledgeBase('banking-knowledgebase')
  .upsertContext(
    {
      contextId: 'credit-cards',
      type: 'file',
      metadata: { company: 'Bank of America', year: 2023 },
    },
    file
  );

その後、filtering context with metadata section に示すように、AIエージェントとのチャットでmetadataを使用できます。

Metadata schemaの定義​

Knowledge Baseにmetadata schemaを宣言すると、metadataが構造化され、自動的に維持されるようになります。Knowledge BaseをupsertするときにフィールドDefinitionを metadataFields で渡します。

Client code
await squid.ai().knowledgeBase('banking-knowledgebase').upsertKnowledgeBase({
  description: 'This Knowledge Base contains information on card data',
  embeddingModel: 'text-embedding-3-small',
  chatModel: 'gpt-5.5',
  metadataFields: [
    { name: 'author', dataType: 'string', required: true, description: 'The full name of the person who wrote the document.' },
    { name: 'publishedAt', dataType: 'date', required: false, description: 'The date the document was published.' },
    { name: 'category', dataType: 'string', required: false, description: 'The document category, for example report, memo, or guide.' },
  ],
});

各フィールドDefinitionは次のとおりです。

FieldTypeRequiredDescription
namestringYes英数字とアンダースコアのみ。text や contextId などの予約名は拒否されます。
dataType'string' | 'number' | 'boolean' | 'date'Yes検証とフィルタリングに使用されます。date 値は範囲フィルターが機能するよう epoch ミリ秒に正規化されます。
requiredbooleanYesフィールドと合わせてエージェントに提示されるヒントです。抽出や取り込みには影響せず、必須の値が見つからない場合でも context は取り込まれます。
descriptionstringNoドキュメントから値を抽出する際、およびエージェントがmetadataフィルターを構築する際のガイドとして使用されます。

TypeScriptの型では dataType に 'array' も宣言されていますが、まだサポートされておらず、Knowledge Base schemaの保存時に拒否されます。

schemaを宣言すると、次の3つが有効になります。指定されたmetadataの検証（型が誤った値はそのcontextのみ拒否）、不足している値の自動抽出、そして agent-driven filtering です。

Metadataの自動抽出​

宣言済みフィールドの値なしでcontextをupsertすると、required の指定に関係なく、Squidが自動的に値を補完します。ファイルアップロードの場合、まずドキュメントプロパティが使用されます。既知のプロパティ名を持つフィールド（title/docTitle、author/docAuthor、createdAt/docCreatedAt、modifiedAt/docModifiedAt、docType）が、PDFやOfficeドキュメントのプロパティ、markdownのfront matter、HTMLのmetadataから補完されます。残りのすべてのフィールドは、各フィールドの description をガイドとしてドキュメントテキストに対するLLMパスで処理されます。ユーザーが指定した値が常に優先され、上書きされることはありません。ただし空文字列は「値なし」とみなされ、引き続き抽出の対象となります。抽出されたフィールド名は保存されたcontextの autoExtractedMetadataFields に記録されます。抽出はベストエフォートであり、見つからない値は欠落したままとなり、アップロードが失敗することはありません。

Knowledge Baseに保存済みの値に基づいてフィールドのdescriptionをSquidに生成させるには、generateMetadataFieldDescriptions() を呼び出します。生成されたdescriptionは保存されずに返されるため、確認のうえ upsertKnowledgeBase() でKnowledge Baseに保存してください。

Client code
const { fields } = await squid
  .ai()
  .knowledgeBase('banking-knowledgebase')
  .generateMetadataFieldDescriptions({ overwriteExisting: false });

MetadataでKnowledge Base Contextをフィルタリングする​

Contextにmetadataを追加した場合、contextMetadataFilterForKnowledgeBase chat optionを使用して、AIエージェントが特定のContextのみを参照するように指示できます。フィルター要件を満たすContextのみが、クライアントpromptへの応答に使用されます。

次の例は、metadata値 "company" が "Bank of America" に等しいものだけを含むようにContextをフィルタリングします。

Client code
await squid
  .ai()
  .agent('banking-copilot')
  .ask('Which Bank of America credit card is best for students?', {
    contextMetadataFilterForKnowledgeBase: {
      ['banking-knowledgebase']: { company: { $eq: 'Bank of America' } },
    },
  });

次のmetadataフィルターがサポートされています。

FilterDescriptionSupported types
$eq指定した値と等しいmetadata値を持つvectorsに一致number, string, boolean
$ne指定した値と等しくないmetadata値を持つvectorsに一致number, string, boolean
$gt指定した値より大きいmetadata値を持つvectorsに一致number
$gte指定した値以上のmetadata値を持つvectorsに一致number
$lt指定した値より小さいmetadata値を持つvectorsに一致number
$lte指定した値以下のmetadata値を持つvectorsに一致number
$in指定した配列に含まれるmetadata値を持つvectorsに一致string, number
$nin指定した配列に含まれないmetadata値を持つvectorsに一致string, number
$exists指定したmetadataフィールドを持つvectorsに一致boolean

スカラー値をそのまま指定すると $eq の省略形になります。つまり { company: 'Bank of America' } と { company: { $eq: 'Bank of America' } } は同等です。フィルターは $and と $or で組み合わせることもできます。

Client code
await squid.ai().agent('banking-copilot').ask('Summarize recent card reports', {
  contextMetadataFilterForKnowledgeBase: {
    ['banking-knowledgebase']: {
      $and: [{ category: 'report' }, { publishedAt: { $gt: Date.parse('2026-01-01') } }],
    },
  },
});

dataType: 'date' で宣言したフィールドは epoch ミリ秒として保存されるため、範囲フィルターには数値（例: Date.parse('2026-01-01')）を渡してください。

Agent-driven metadata filtering​

Knowledge Baseが metadata schemaを宣言している場合、接続されたエージェントは自らmetadataフィルターを構築できます。Knowledge Baseの検索ツールに filter パラメータが追加され、モデルは各フィールドのdescriptionとツールのdescriptionに示される少数のサンプル値をガイドとして、ユーザーの質問に基づきフィルターを組み立てます。

contextMetadataFilterForKnowledgeBase で設定したフィルターは常に適用され、エージェントのフィルターと AND で結合されます。エージェントは許可された範囲を狭めることはできても、広げることは決してできないため、アプリレベルのフィルターはセキュリティ境界として機能し続けます。

接続されたKnowledge Baseで enableMetadataInspection: true を設定すると、エージェントはフィールドの保存済みの値をオンデマンドで列挙・検索するインスペクションツールも利用でき、正確なフィルターの構築に役立ちます。値は直近に更新されたドキュメントからサンプリングされるため、サンプルに値がないことはその値が存在しないことの証明にはなりません。

ベストプラクティス​

  • 大きなドキュメントはトピックごとに焦点を絞ったKnowledge Baseに分割します。これにより、適切なContextを選ぶためのシグナルが強くなります。
  • Contextにmetadataを追加して、クエリ時のフィルタリングを有効にし、応答のノイズを減らします。