グロッサリー
ビジネス用語の意味を定義して、エージェントやAIクエリが「アクティブな顧客」や「解約」を自社の意味で解釈できるようにします。
グロッサリーを使用する理由
ユーザーはビジネスの言葉で質問します。「アクティブな顧客は何人いますか?」という質問の答えは、「アクティブ」が何を意味するかによって異なります。過去90日以内の注文、有料プラン、今月のログインなどが考えられます。定義がなければ、AIモデルがいずれかを選択するため、答えは正しく見えても、誤った行を数えることになります。
グロッサリーの用語を使えば、一度の定義で対応できます。
Active Customer: A customer who placed an order in the last 90 days.
synonyms: Active Account
collections: customers, orders
query snippet: last_order_at >= CURRENT_DATE - INTERVAL '90 days'
AIクエリとエージェントは、質問ごとに関連する用語を受け取るため、推測する代わりに定義を使用します。
概要
グロッサリーには用語を登録します。各用語には name と平易な言葉による description があり、任意で synonyms を設定できます。グロッサリーはモデルへの指針です。SquidはAIクエリとエージェントに用語を渡しますが、クエリを強制したり書き換えたりすることはありません。
グロッサリーには2種類あります。
- データベースグロッサリー。 各データベースコネクターには最大1つあり、
scope: { type: 'database', integrationId }を持ちます。用語には、関連するcollectionsと、そのデータベースのクエリ言語によるquerySnippetも指定できます。 - グローバルグロッサリー。
scope: { type: 'global' }を持ち、どのデータベースにも属しません。「Fiscal Quarter」のような全社共通の語彙を扱います。用語にcollectionsやquerySnippetはありません。IDでエージェントやオントロジーに関連付けます。
Squidは、データベーススキーマとナレッジベースから用語を生成できます。生成時に保存は行われず、確認して保存するためのドラフトが返されます。
クイックスタート
前提条件
- データベースグロッサリーの場合、スキーマが検出済みのデータベースコネクター。
- Squid backend SDK。グロッサリーの管理にはアプリのAPIキーが必要なため、バックエンドコードから実行し、executableを通じてフロントエンドに公開してください。
グロッサリーAPIはTypeScript SDKで利用できます。
ステップ1:データベースグロッサリーを保存する
import { SquidService, executable } from '@squidcloud/backend';
import { Glossary } from '@squidcloud/client';
export class GlossaryService extends SquidService {
@executable()
async saveSalesGlossary(): Promise<Glossary> {
// Saves the glossary with exactly these terms. A database glossary is found by its database.
return this.squid
.ai()
.glossary()
.saveGlossary({
glossary: {
name: 'Sales glossary',
scope: { type: 'database', integrationId: 'sales_db' },
},
terms: [
{
name: 'Active Customer',
description: 'A customer who placed an order in the last 90 days.',
synonyms: ['Active Account'],
collections: ['customers'],
querySnippet: "last_order_at >= CURRENT_DATE - INTERVAL '90 days'",
},
{
name: 'Fiscal Quarter',
description: 'Our fiscal quarters start in February, May, August and November.',
},
],
});
}
}
ステップ2:質問する
sales_db に対するAIクエリは、関連する用語を受け取るようになります。providedDefinitions には、モデルに渡された用語が一覧表示されます。
import { SquidService, executable } from '@squidcloud/backend';
export class SalesQuestionService extends SquidService {
@executable()
async countActiveCustomers(): Promise<string> {
const response = await this.squid.ai().executeAiQuery('sales_db', 'How many active customers do we have?');
// For example: [{ type: 'term', id: '...', name: 'Active Customer' }]
console.log(response.providedDefinitions);
return response.answer;
}
}
エージェントに用語を渡すには、データベースをエージェントに接続します。接続されたオントロジーとグロッサリーを参照してください。
基本概念
用語
| フィールド | 説明 |
|---|---|
name | 「Active Customer」などの用語。グロッサリー内で一意であり、大文字と小文字、スペースの違いは区別されません。 |
description | 技術的な内容を含まない、平易な言葉による定義。データベースグロッサリーの説明では、用語がどこに存在するかを言葉で記述できます。 |
synonyms | 「Account」に対する「Customer」など、その用語を指すために使われる別の言葉。最大20個。同義語を使った質問は、その用語を指定したものとして扱われます。 |
collections | データベースグロッサリーのみ:用語に関連するコレクション。空の場合はデータベース全体を意味します。一部のコレクションに制限されたエージェントやAIクエリには、それらに対応する用語のみが表示されます。 |
querySnippet | データベースグロッサリーのみ:用語に該当するものを選択する、データベースのクエリ言語による断片。最大2,000文字。AIクエリはこれをルールではなくヒントとしてモデルに提示します。 |
保存とリビジョン
saveGlossary() はすべての用語を置き換えます。保存される用語は、送信した用語と完全に同じになります。書き込みのたびにグロッサリーの revision が増加します。読み取った revision を渡すと、その後に誰かがグロッサリーを保存していた場合、保存は GLOSSARY_REVISION_CONFLICT で失敗します。
送信する revision | 効果 |
|---|---|
| 省略 | 保存済みの内容にかかわらず置き換えます |
0 | グロッサリーを読み取っていないため、その後に保存されていた場合は失敗します |
| 数値 | 保存済みのリビジョンがより新しい場合、保存は失敗します |
残りの用語を送信せずに1つの用語を変更するには、updateTerm() と deleteTerm() を使用します。
import { SquidService, executable } from '@squidcloud/backend';
import { GlossaryTerm } from '@squidcloud/client';
export class GlossaryTermService extends SquidService {
@executable()
async addPartnerTerm(glossaryId: string): Promise<GlossaryTerm> {
// A term with no id, or an unknown one, is added.
return this.squid.ai().glossary().updateTerm(glossaryId, {
name: 'Partner',
description: 'A company that resells our products.',
});
}
@executable()
async listTerms(glossaryId: string): Promise<GlossaryTerm[]> {
// listTerms({ glossaryId, cursor, limit, search }) reads one page at a time.
return this.squid.ai().glossary().listAllTerms(glossaryId);
}
}
削除された名前
用語を削除するか、生成された用語を保存前に除外すると、グロッサリーはその名前を記憶し、生成時に再び提案しないようにします。listExcludedNames(glossaryId) で名前の一覧を取得でき、restoreExcludedName(glossaryId, name) で再び生成時に提案されるようにできます。
グロッサリーの生成
generateGlossary() はソースを読み取り、変更内容とそれぞれの理由を含むドラフトを返します。保存は行いません。
- データベースグロッサリーは、そのデータベースのスキーマを読み取ります。
- グローバルグロッサリーは、
integrationIdsに含まれるデータベースのグロッサリーと、knowledgeBaseIdsに含まれるナレッジベースのナレッジグラフを読み取ります。
| オプション | デフォルト | 説明 |
|---|---|---|
mode | update | update はソースに基づいて必要最小限の変更を返します。regenerate は以前の用語や削除された名前を使わず、ソースのみから用語を構築します。 |
instructions | 「ロイヤルティプログラムの用語を追加する」など、この実行にのみ適用する追加の指示。保存されません。グロッサリー自体の instructions も引き続き適用されます。 | |
terms | 保存済みの用語 | 更新対象の現在のドラフト。 |
グロッサリーの保存元となった生成以降にソースが変更されていない場合、update はモデルを呼び出さずに unchanged: true を返します。instructions を指定した実行では、常にモデルが呼び出されます。
import { SquidService, executable } from '@squidcloud/backend';
import { Glossary } from '@squidcloud/client';
export class GlossaryGenerationService extends SquidService {
@executable()
async generateAndSave(): Promise<Glossary> {
const glossaries = this.squid.ai().glossary();
const glossary = {
name: 'Sales glossary',
scope: { type: 'database', integrationId: 'sales_db' } as const,
};
const current = await glossaries.getDatabaseGlossary('sales_db');
const draft = await glossaries.generateGlossary({
glossary: { ...glossary, id: current?.id },
mode: 'update',
});
// Each change is { type: 'add' | 'update' | 'remove' | 'merge', name, reason, ... }.
for (const change of draft.changes) console.log(`${change.type} ${change.name}: ${change.reason}`);
return glossaries.saveGlossary({
glossary: { ...glossary, id: current?.id },
terms: draft.terms,
// Lets a later update skip the model when nothing changed.
generatedFrom: draft.generatedFrom,
// 0 when no glossary was stored yet.
revision: current?.revision ?? 0,
});
}
}
ドラフトから除外した生成済みの用語を droppedNames として saveGlossary() に渡すと、生成時に再び提案されなくなります。
regenerateの実行で得たドラフトを保存するときは、regenerated: trueを渡します。これにより、グロッサリーはこの保存より前に記憶していた名前を破棄します。どちらの場合も、渡したdroppedNamesと、新しいドラフトにない保存済みの用語はすべて記憶され、以降の実行で提案されなくなります。いずれかを再び生成で提案できるようにするには、restoreExcludedName()を呼び出します。
グローバルグロッサリー
グローバルグロッサリーには、1つのデータベースに結び付かない語彙を登録します。生成元となるソースを指定し、エージェントやオントロジーに関連付けます。
import { SquidService, executable } from '@squidcloud/backend';
export class CompanyGlossaryService extends SquidService {
@executable()
async createCompanyGlossary(): Promise<string> {
const saved = await this.squid
.ai()
.glossary()
.saveGlossary({
glossary: {
name: 'Company vocabulary',
scope: { type: 'global' },
integrationIds: ['sales_db'],
instructions: 'We are a B2B distributor. Skip HR terms.',
},
terms: [{ name: 'Fiscal Quarter', description: 'Our fiscal quarters start in February.' }],
});
return saved.id;
}
}
グロッサリーの使用場所
- AIクエリ。 データベースグロッサリーの関連用語が、コレクションやクエリスニペットとともに各段階で指針となります。個別のクエリでは、AIクエリオプションの
semanticLayer: { enabled: false }でこれを無効にできます。 - エージェント。 接続されたデータベースの用語は、名前、同義語、説明の最初の文がエージェントの指示に表示されます。コレクションやクエリスニペットは表示されません。エージェントに関連付けられたグローバルグロッサリーも表示されます。接続されたオントロジーとグロッサリーを参照してください。
- オントロジーの生成。 生成時には、関連付けられたデータベースのグロッサリーと、オントロジーの
glossaryIdsに含まれるグローバルグロッサリーが読み取られます。グロッサリーによる生成のガイドを参照してください。
エラー処理
| エラー | 原因 | 解決方法 |
|---|---|---|
GLOSSARY_REVISION_CONFLICT | 送信した revision 以降にグロッサリーが保存された | グロッサリーを再度読み取り、変更を再適用して保存する |
GLOSSARY_NOT_FOUND | グロッサリーIDが存在しないか、リビジョンを指定した保存時に削除済みだった | listGlossaries() でIDを探す |
GLOSSARY_TERM_NAME_TAKEN | グロッサリー内の別の用語が同じ名前を持つ | 用語の名前を変更するか、既存の用語を更新する |
ベストプラクティス
- 少数の幅広い用語に絞る。 すべての列ではなく、ユーザーが実際に質問する用語や、スキーマが誤って解釈する用語を定義します。
- 人にわかる説明を書く。 説明は平易な言葉で記述します。技術的な部分は
querySnippetに入れます。 - ユーザーが使う言葉を同義語にする。 ユーザーが「account」と呼び、テーブルでは「customer」となっている場合は、同義語を追加します。
- 生成されたドラフトを確認する。 生成は提案であり、判断するのはユーザーです。適切でない用語は除外し、
droppedNamesとして渡します。 - リビジョンを指定して保存する。 複数の人やプロセスがグロッサリーを編集する場合は、
revisionを渡して、保存時に他の変更を上書きしないようにします。