搜尋

此頁面顯示開發人員專用範圍設定協助程式以及具體 Oracle 搜尋結果類型。

範圍解決方式

對於每個範圍欄位，您可以執行下列三項作業之一：

• 省略以使用該 API 層的預設值。在 Python 簽章和 SearchScope 中，此省略狀態是由 NOT_SET_MARKER 表示。
• 指定具體 ID 以使用該值；
• 指定 None 來表示該維度上的記錄未作用領域。例如，agent_id=None 表示記錄未連結至一個專員。

每個儲存的記錄都有三個獨立的範圍欄位：user_id、agent_id 和 thread_id。每個欄位都可以有一個具體 ID 或 None。

範例：

• thread_id=None 表示記錄未連結至一個執行緒。
• agent_id=None 表示記錄未連結至一個專員。
• user_id="u1", agent_id=None, thread_id=None 表示記錄的作用領域為使用者 u1，而不是任何特定專員或執行緒。

相同的範圍規則同時適用於同步與非同步搜尋 API。

在下表中，ID 代表任何 user_id、agent_id 或 thread_id 以及其對應的完全相符旗標。

依 API 層搜尋範圍解決方式

案例	中文 (繁體)	繁體中文 (香港)	中文 (繁體)
省略的 ID	使用繫線預設值：精確的 user_id 和 agent_id，加上目前含有 exact_thread_match=False 的 thread_id。	使用用戶端預設值。省略的 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	僅符合該維度上未限制範圍的記錄。	僅符合該維度上未限制範圍的記錄。	僅符合該維度上未限制範圍的記錄。

當您只想在該維度上取消作用領域，且 API 允許記錄時，請將明確的 None 與 exact_*_match=True 一起使用。若要改為預設作業，請省略欄位。

範圍

類別 oracleagentmemory.apis.scope.Scope

基礎：object

代表資訊插入或搜尋的範圍。

• 參數：
  • user_idstr | None
  • 代理程式 ID str | None
  • thread_id str | None

user_id

一般用戶 ID。NOT_SET_MARKER 表示欄位已被省略，且應由作業特定的預設值來解析。作業特定規則會保留並解譯明確的 None。較高階的從屬端 API (例如 OracleAgentMemory.search()) 可能需要明確的使用者範圍。在這些 API 中，None 只能用來鎖定未限制範圍的記錄。

• 類型： str | 無

代理程式識別碼

代理程式 ID。NOT_SET_MARKER 表示欄位已被省略，且應由作業特定的預設值來解析。作業特定規則會保留並解譯明確的 None。

• 類型： str | 無

執行緒 ID

繫線 ID。NOT_SET_MARKER 表示欄位已被省略，且應由作業特定的預設值來解析。作業特定規則會保留並解譯明確的 None。

• 類型： str | 無

類別 oracleagentmemory.apis.searchscope.SearchScope

基本：Scope

代表搜尋查詢的範圍，因此會限制可傳回的項目。

• 參數：
  • user_idstr | None
  • 代理程式 ID str | None
  • thread_id str | None
  • exact_user_matchbool
  • exact_agent_matchbool
  • exact_thread_match bool

user_id

一般用戶 ID。當解析的 exact_user_match 值為 True 時，此 ID 會完全相符，包括 None。如果是 False，則不會限制使用者維度。NOT_SET_MARKER 會由作業特定的預設值取代。較高階的從屬端 API (例如 OracleAgentMemory.search()) 可能需要明確的使用者範圍。在這些 API 中，None 只會在 exact_user_match 解析為 True 時鎖定未作用領域的記錄。

• 類型： str | 無

代理程式識別碼

代理程式 ID。當解析的 exact_agent_match 值為 True 時，此 ID 會完全相符，包括 None。如果是 False，則不會限制代理程式維度。視使用範圍的作業而定，NOT_SET_MARKER 會由預設值取代。

• 類型： str | 無

執行緒 ID

繫線 ID。當解析的 exact_thread_match 值為 True 時，此 ID 會完全相符，包括 None。當其為 False 時，繫線維度會不受限制。視使用範圍的作業而定，NOT_SET_MARKER 會由預設值取代。

• 類型： str | 無

精確使用者比對

是否完全符合解析的 user_id。True 完全符合，包括 None。False 會讓使用者維度不受限制。根據作業的不同，預設會取代 NOT_SET_MARKER。較高階的從屬端 API (例如 OracleAgentMemory.search()) 可能需要保留 True。

• 類型：布林值

完全相符的代理程式

是否完全符合解析的 agent_id。True 完全符合，包括 None。False 會讓代理程式維度不受限制。根據作業的不同，預設會取代 NOT_SET_MARKER。

• 類型：布林值

精確執行緒相符

是否完全符合解析的 thread_id。True 完全符合，包括 None。False 會讓繫線維度不受限制。根據作業的不同，預設會取代 NOT_SET_MARKER。

• 類型：布林值

結果

類別 oracleagentmemory.core.OracleSearchResult

基本：SearchResult

Oracle 執行緒傳回的搜尋結果。

• 參數：
  • distance float – 與查詢向量的距離 (越小越好)。
  • 記錄 Record – 包含持續項目相關中繼資料資訊的記錄物件。
  • id str | None – 與已儲存記錄關聯的選擇性識別碼。

特性 content

• 傳回類型： str
• 描述：傳回相符記錄的主要文字內容。

特性 formatted_content

• 傳回類型： str

• 描述：傳回提示中使用的預設 XML 安全轉譯。

• 傳回：包含搜尋結果預設可見欄位的 XML 安全轉譯。
• 傳回類型： str

特性 id

• 傳回類型： str | 無
• 描述：如果可用，則傳回相符記錄的穩定識別碼。

特性 metadata

• 傳回類型： dict[str，Any] | None
• 描述：傳回記錄描述資料 (如果有的話)。

特性 record

• 傳回類型：記錄
• 描述：傳回相符的記錄。

傳回的值可以是純 Record 或 ScopedRecord 子類別。讀取公用範圍 ID 之前，請先使用 isinstance(result.record, ScopedRecord)。

特性 timestamp

• 傳回類型： str | 無
• 描述：傳回記錄時戳 (如果有的話)。