搜尋

此頁面顯示開發人員專用範圍設定協助程式以及具體 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 層搜尋範圍解析

案例	thread.search()	OracleAgentMemory.search()	store.search()
省略的 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 一起使用。若要改為預設作業，請省略欄位。

生命週期狀態篩選

所有持續的記錄都有生命週期狀態。搜尋會接受存放區、從屬端和繫線 API 上的 include_invalid_results。在用戶端與執行緒 API 上，預設為 NOT_SET_MARKER，這會解析為在搜尋結果中包含有效與無效的記錄。下層存放區 API 會將其布林預設值解析為相同的行為。傳送 False 以省略狀態為 RecordStatus.INVALID 的記錄。

圖形展開

將 num_hops 從 0 傳送至 5 至存放區、從屬端或繫線搜尋 API，以將連結的記憶體相關資訊環境附加至每個直接記憶體結果。遍訪依循任一方向的關係，保留儲存的關係方向，並傳回每個記錄之 linked_results 序列的最短路徑樹狀結構。直接訊息、文件和動作者設定檔相符項目會保留在排名結果集中，但不會展開圖表。特別是，可搜尋的影像描述可以傳回影像記錄，而不需要讓 DOCUMENT 成為記憶體連結頂點。範圍、描述資料、記錄類型以及到期篩選會套用至每個連結的記憶體。include_invalid_results 會繼續只控制最上層搜尋相符項目；不會變更包含哪些連結的記憶體。max_linked_results 會將所有躍點連附至每個直接結果的連結記憶體總計限制在內。它預設為 100；傳送 0 以省略連結的相關資訊環境。

範圍

類別 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.MemorySearchConfig

基本：ISearchConfig

搜尋後行為記憶體的基礎組態。

• 參數：
  • token_budget int | None
  • soft_token_budget int | None

格式化搜尋輸出的目標大小 (選擇性)。

在達到或超過此預算的第一個結果中，完整結果會以排名順序排列。因此，當沒有永久 token_budget 時，會保留第一個結果，以防止傳回結果。

預估格式化搜尋輸出大小的選擇性嚴格限制。

完整結果會以排名順序保留，而其累積預估則符合預算。如果第一個結果不符合，則不會傳回任何結果。

類別 oracleagentmemory.core.TopKMemorySearchConfig

基本：_RerankingMemorySearchConfig

具有固定最大直接結果數的搜尋組態。

• 參數：
  • token_budget int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidatesint
  • 最大結果 int

重新排名前擷取的最大直接結果數。

類別 oracleagentmemory.core.PruningEvaluationMode

基礎：str、Enum

控制在刪減期間評估廣泛搜尋結果的方式。

排斥 = 'EXHAUSTIVE'

個別評估每個應徵者結果。這可提供最完整的評估，但具有最高的延遲和 LLM 使用量。

延伸 = 'EXTENDED'

以額外的延遲和 LLM 使用成本，在決定要保留哪些結果之前，評估更廣泛的部分。

快速 = 'FAST'

進一步的檢查不太可能變更保留的結果，可提早停止評估以確定低延遲的優先順序。

類別 oracleagentmemory.core.PruningMemorySearchConfig

基本：_RerankingMemorySearchConfig

可移除較少相關直接結果的搜尋組態。

每次搜尋或環境定義卡呼叫會提供直接結果限制，並在重新排序與刪減前套用。

• 參數：
  • token_budget int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidatesint
  • evaluation_mode PruningEvaluationMode
  • num_probe_pointsint
  • protected_fraction float
  • pruner ILlm

刪減期間評估廣泛搜尋結果的方式。

省略時，會使用 PruningEvaluationMode.FAST。

以 FAST 或 EXTENDED 模式評估的排名結果區域數目。

evaluation_mode 為 PruningEvaluationMode.EXHAUSTIVE 時，無法設定此參數。

受保護免於刪減之最高排名直接結果的分數。

例如，0.1 可保護前 10% 的直接結果。

用來決定要移除哪些直接結果的 LLM。

結果

類別 oracleagentmemory.core.SearchResultFormatConfig

基礎：object

控制可攜式搜尋結果轉譯選項。

實行可以提供子類別以及其他轉換選項。

• 參數： include_invalid_results bool – 無效的連結記錄是否包含其內容。False 時，會省略僅無效的分支，而有效記錄路徑上的無效記錄則會保留其狀態與連結內容。省略以使用 True。

類別 oracleagentmemory.core.OracleSearchResultFormatConfig

基本：SearchResultFormatConfig

控制 Oracle 搜尋結果轉譯選項。

• 參數：
  • show_thread_id bool – 是否要包含記錄的執行緒識別碼。省略以使用 False。
  • show_distance bool – 是否包含預估的相關性。省略以使用 False。
  • show_timestamp bool – 是否包含記錄時間戳記。省略以使用 True。
  • show_role bool – 是否包含訊息角色。省略以使用 True。
  • show_user_id bool – 是否包含記錄使用者識別碼。省略以使用 False。
  • show_agent_id bool – 是否包含記錄代理程式識別碼。省略以使用 False。
  • show_status bool – 是否包含記錄生命週期狀態。省略以使用 True。
  • show_metadata bool – 是否在出現時包含呼叫程式描述資料與記憶體無效驗證原因。每個項目都會使用其描述資料索引鍵作為 XML 標記，並將其值轉譯為字串。省略以使用 False。
  • include_invalid_results bool

類別 oracleagentmemory.core.OracleSearchResult

基本：SearchResult

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

• 參數：
  • distance float – 與查詢向量的距離 (越小越好)。
  • 記錄 Record – 包含持續項目相關中繼資料資訊的記錄物件。
  • id str | None – 與已儲存記錄關聯的選擇性識別碼。
  • linked_results list tuple[[RecordRelation, SearchResult]] | None – 選擇性圖表連結的子項結果。每組都包含儲存的 RecordRelation 以及透過它取得的結果。
  • format_config SearchResultFormatConfig – 未提供任何選項時，formatted_content 與 format_content() 所使用的預設轉譯選項。

特性 content

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

方法 format_content

將此結果及其圖表相關資訊環境轉譯為 XML 安全提示文字。

• 參數： format_config SearchResultFormatConfig – 此呼叫的轉換選項。省略以使用此結果的預設組態。在提供的組態中，省略的選項會轉為該預設組態中對應的選項。
• 傳回：XML 安全結果轉譯。
• 傳回類型： str

特性 formatted_content

• 傳回類型： str

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

• 傳回：使用此結果之預設組態的 XML 安全轉譯。
• 傳回類型： str

特性 id

• 傳回類型： str

  無

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

特性 linked_results

• 傳回類型： list[tuple[ RecordRelation ，SearchResult]]
• 描述：以遞迴的最短路徑樹狀結構傳回連結的結果。

特性 metadata

• 傳回類型： dict[str，Any]

  無

• 描述：傳回記錄描述資料 (如果有的話)。

特性 record

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

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

特性 status

• 傳回類型：記錄狀態

  無

• 描述：傳回相符記錄的生命週期狀態。

特性 timestamp

• 傳回類型： str

  無

• 描述：傳回記錄時戳 (如果有的話)。