検索

このページでは、開発者向けスコープ指定ヘルパーと、具体的なOracle検索結果タイプを示します。

スコープ解決

スコープ・フィールドごとに、次の3つのうちのいずれかを実行できます。

• そのAPIレイヤーのデフォルトを使用するように省略します。Python署名およびSearchScopeでは、この省略された状態はNOT_SET_MARKERで表されます。
• その値を使用する具体的なIDを指定します。
• Noneを指定すると、そのディメンションでレコードのスコープが解除されます。たとえば、agent_id=Noneは、レコードが1つのエージェントに関連付けられていないことを意味します。

各ストアド・レコードには、user_id、agent_idおよびthread_idの3つの独立したスコープ・フィールドがあります。各フィールドは、具象IDまたはNoneを保持できます。

次に例を示します:

• thread_id=Noneは、レコードが1つのスレッドに関連付けられていないことを意味します。
• agent_id=Noneは、レコードが1つのエージェントに関連付けられていないことを意味します。
• user_id="u1", agent_id=None, thread_id=Noneは、レコードがユーザーu1にスコープ指定されるが、特定のエージェントまたはスレッドにはスコープ指定されないことを意味します。

同期検索APIと非同期検索APIの両方に、同じ範囲指定ルールが適用されます。

次の表では、IDは、対応する完全一致フラグとともに、user_id、agent_idまたはthread_idのいずれかを意味します。

APIレイヤーによるスコープ解決の検索

ケース	スレッド検索()	OracleAgentMemory検索()	ストア検索()
IDが省略されました	スレッドのデフォルト値(正確なuser_idとagent_id、および現在のthread_idとexact_thread_match=False)を使用します。	クライアントのデフォルトを使用します。省略されたuser_idは拒否されます。省略されたagent_idおよびthread_idは広範囲に保たれます。	ディメンションがフィルタされないように、ストア・デフォルト(ID=Noneおよびexact_*_match=False)を使用します。
明示的な値(None + exact_*_match=Falseを含む)	そのディメンションはフィルタされません。値が指定されたレコードと一致するレコードは、他のレコードよりもランクが高くなる可能性があります。	user_idの場合、クライアント検索には明示的な正確なユーザー・スコープ指定が必要であるため、拒否されます。agent_idおよびthread_idの場合、そのディメンションはフィルタされません。値が指定されたレコードと一致するレコードは、他のレコードよりもランクが高くなる可能性があります。	そのディメンションはフィルタされません。値が指定されたレコードと一致するレコードは、他のレコードよりもランクが高くなる可能性があります。
明示的なID + exact_*_match=True	そのIDに正確に一致します。	そのIDに正確に一致します。	そのIDに正確に一致します。
明示的なNone + exact_*_match=True	そのディメンションでスコープ指定されていないレコードのみに一致します。	そのディメンションで有効範囲なしのレコードのみに一致します。	そのディメンションで有効範囲なしのレコードのみに一致します。

明示的なNoneをexact_*_match=Trueとともに使用すると、そのディメンションでスコープ指定されていないレコードのみが許可され、APIで許可されます。操作をデフォルトにする場合は、フィールドを省略します。

スコープ

クラス oracleagentmemory.apis.scope.Scope

ベース: object

情報の挿入または検索のスコープを表します。

• パラメータ:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None

user_id

エンドユーザーのID。NOT_SET_MARKERは、フィールドが省略され、操作固有のデフォルトによって解決される必要があることを意味します。明示的なNoneは、操作固有のルールによって保持および解釈されます。OracleAgentMemory.search()などの上位レベルのクライアントAPIでは、ユーザー・スコープを明示する必要がある場合があります。これらのAPIでは、Noneを使用して、スコープなしレコードのみをターゲットにできます。

• タイプ: str | None

エージェントID

エージェントID NOT_SET_MARKERは、フィールドが省略され、操作固有のデフォルトによって解決される必要があることを意味します。明示的なNoneは、操作固有のルールによって保持および解釈されます。

• タイプ: str | None

スレッドID

スレッドID。NOT_SET_MARKERは、フィールドが省略され、操作固有のデフォルトによって解決される必要があることを意味します。明示的なNoneは、操作固有のルールによって保持および解釈されます。

• タイプ: str | None

クラス oracleagentmemory.apis.searchscope.SearchScope

ベース: Scope

検索問合せのスコープを表すため、返される内容を制限します。

• パラメータ:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None
  • exact_user_match bool
  • exact_agent_match bool
  • exact_thread_match bool

user_id

エンドユーザーのID。解決されたexact_user_match値がTrueの場合、このIDはNoneも含めて完全に一致します。Falseの場合、ユーザー・ディメンションは制約されません。NOT_SET_MARKERは、操作固有のデフォルトに置き換えられます。OracleAgentMemory.search()などの上位レベルのクライアントAPIでは、ユーザー・スコープを明示する必要がある場合があります。これらのAPIでは、exact_user_matchがTrueに解決された場合、Noneはスコープなしレコードのみをターゲットとします。

• タイプ: str | None

エージェントID

エージェントID 解決されたexact_agent_match値がTrueの場合、このIDはNoneも含めて完全に一致します。Falseの場合、エージェント・ディメンションは制約されません。NOT_SET_MARKERは、スコープを使用する操作に応じてデフォルト値に置き換えられます。

• タイプ: str | None

スレッドID

スレッドID。解決されたexact_thread_match値がTrueの場合、このIDはNoneも含めて完全に一致します。Falseの場合、スレッド・ディメンションは制約されません。NOT_SET_MARKERは、スコープを使用する操作に応じてデフォルト値に置き換えられます。

• タイプ: str | None

完全一致

解決されたuser_idと完全に一致するかどうか。Trueは、Noneを含む厳密に一致します。Falseは、ユーザー・ディメンションを制約なしのままにします。NOT_SET_MARKERは、操作に応じてデフォルトで置き換えられます。OracleAgentMemory.search()などの上位レベルのクライアントAPIでは、これをTrueのままにする必要がある場合があります。

• タイプ: bool

完全一致エージェント

解決されたagent_idと完全に一致するかどうか。Trueは、Noneを含む厳密に一致します。Falseは、エージェント・ディメンションを制約なしのままにします。NOT_SET_MARKERは、操作に応じてデフォルトで置き換えられます。

• タイプ: bool

完全スレッド一致

解決されたthread_idと完全に一致するかどうか。Trueは、Noneを含む厳密に一致します。Falseは、スレッド・ディメンションを制約なしのままにします。NOT_SET_MARKERは、操作に応じてデフォルトで置き換えられます。

• タイプ: bool

結果

クラス oracleagentmemory.core.OracleSearchResult

ベース: SearchResult

Oracleスレッドによって返された検索結果。

• パラメータ:
  • distance float– 問合せベクトルからの距離(小さい方が良い)。
  • record Record– 永続化されたエントリに関するメタデータ情報を含むレコードオブジェクト。
  • id str | None– 格納されたレコードに関連付けられたオプションの識別子。

プロパティ content

• 戻りタイプ: str
• 説明:一致したレコードのプライマリ・テキスト・コンテンツを返します。

property formatted_content

• 戻りタイプ: str

• 説明:プロンプトで使用されるデフォルトのXMLセーフ・レンダリングを返します。

• 戻り値:検索結果のデフォルトの可視フィールドを含むXMLセーフ・レンダリング。
• 戻り型: str

プロパティー id

• 戻り型: str | None
• 説明:一致したレコードの安定した識別子(使用可能な場合)を返します。

property metadata

• 戻り型: dict[str、 Any] | None
• 説明:レコード・メタデータ(使用可能な場合)を返します。

property record

• 戻りタイプ: レコード
• 説明:一致したレコードを返します。

戻り値は、プレーンなRecordまたはScopedRecordサブクラスです。パブリック・スコープ識別子を読み取る前に、isinstance(result.record, ScopedRecord)を使用します。

property timestamp

• 戻り型: str | None
• 説明:レコード・タイムスタンプ(使用可能な場合)を返します。