繫線數目

此頁面顯示具體 Oracle 執行緒處理與開發人員專用訊息協助程式類型。

Oracle 執行緒

類別 oracleagentmemory.core.OracleThread

基本：IThread

由 Oracle 商店支援的執行緒。

此實作會內嵌並儲存執行緒訊息與手動新增的記憶，然後支援所有儲存記錄的相似性搜尋。

注意事項

• 訊息儲存為個別記錄 (每則訊息一筆記錄)。
• 您可以將搜尋限制在目前的執行緒，或是允許從任何執行緒 (由用戶端控制) 傳回結果。

建立新的執行緒處理。

• 參數：
  • store OracleMemoryStore – 用來保存內嵌記錄的共用存放區後端。
  • thread_id str – 繫線 ID。若未提供，則會產生 UUID。
  • user_id str – 與執行緒關聯的使用者識別碼。如果省略，則會產生 UUID。
  • agent_id str – 與繫線關聯的代理程式 ID。如果省略，則會產生 UUID。
  • persist_messages_in_config bool – _to_config 是否應包含最近的原始訊息快照。針對使用資料庫存放區的繫線自動設為 False，以避免透過繫線組態匯出訊息表格內容。
  • LLM ILlm | None – 選用的 LLM 轉接器，用於記憶體擷取和相關資訊環境摘要更新。提供時，add_messages 會從每個新增的訊息擷取相關備忘錄，並將其儲存為 record_type="memory"。
  • memory_extraction_window int – 擷取期間要提供作為 LLM 相關資訊環境的最近訊息數目 (包括新新增的訊息)。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。預設為 -1。
  • context_summary_update_frequency int – 應更新相關資訊環境摘要的訊息數目。設為 -1，即可使用整批新增的訊息，針對每一 add_messages 呼叫彙總一次。在成績單寫入期間，會重複使用相同的節奏來重新整理執行緒彙總中繼資料。
  • memory_extraction_frequency int – 觸發記憶體擷取的訊息數目。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。
  • memory_extraction_token_limit int – 記憶體擷取中所使用提示的大小上限 (記號)。較長的提示將會被截斷。如果為負數或 0，則不會執行截斷。
  • max_message_token_length int – LLM 備份的記憶體擷取和相關資訊環境摘要更新期間，每個訊息的提示時間複本大小上限 (記號)。儲存的訊息內容維持不變。若為負數或 0，則不會執行提示時間縮短。如果提供 LLM，則會彙總過大小的提示複本，而非截斷。
  • message_shortening_input_token_limit int – 縮短過大提示複本時，傳送給 LLM 之訊息摘錄的最大大小 (記號)。預設為 30_000 記號。如果為負數或 0，則在 LLM 型縮短期間不會套用輸出界限。
  • enable_context_summary bool – 是否保留執行緒的精簡執行摘要。如果啟用且提供 llm，就會根據 context_summary_update_frequency 更新摘要。擷取記憶時，目前摘要會提供為內容。
  • 用戶端 Any | None

範例

from oracleagentmemory.core import OracleAgentMemory
db_pool = ...
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    enable_context_summary=True,
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

方法 add_memory

新增手動記憶體項目並為其編製索引。

• 參數：
  • content str – 要儲存為記憶體的文字內容。
  • user_id str – 選擇性的使用者 ID 覆寫。
  • agent_id str – 選擇性代理程式 ID 覆寫。
  • thread_id str – 選擇性繫線 ID 覆寫。
  • memory_id str – 此記憶體資料列的選擇性呼叫程式提供穩定 ID。
  • **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
• 傳回：插入之記憶體記錄的 ID。
• 傳回類型： str

範例

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

方法 add_messages

新增訊息到討論串並建立它們索引。

• 參數：
  • messages list[Message | MessageT] – 要附加的訊息清單。訊息可以是 Message 物件或含有 role 和 content 的字典 (以及選擇性的 id)。
  • **store_kwargs ( 任一 ) – 轉送至備份存放區的存放區特定寫入選項。
• 傳回：插入之訊息記錄的識別碼。
• 傳回類型： list[str]

範例

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

方法 add_messages_async (非同步)

非同步地新增信件到串列中，並為其建立索引。

• 參數：
  • 訊息 list[Message | MessageT]
  • store_kwargs Any
• 傳回類型： list[str]

方法 delete_memory

依 ID 刪除此精確繫線的記憶體記錄。

• 參數： memory_id str – 記憶體 ID。只有儲存的 thread_id 完全符合此繫線的記憶體會被刪除。
• 傳回數：刪除的記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數

範例

thread.delete_memory("456")
0

方法 delete_message

依識別碼從此精確執行緒刪除訊息記錄。

• 參數： message_id str – 訊息 ID。只會刪除儲存的 thread_id 完全符合此討論串的訊息。
• 傳回數：刪除的記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數

注意事項

成功刪除會清除衍生的繫線摘要狀態，因此稍後摘要和相關資訊環境卡呼叫會從剩餘的成績單重建。衍生的記憶體不會自動刪除，因為擷取的記憶體目前並未保留每個訊息的來源。

範例

thread.delete_message("123")
0

方法 get_context_card

傳回執行緒的類似 XML 內容卡。

在 LLM 備份的實作可能執行遠端網路 I/O 時，偏好使用 get_context_card_async。

• 參數：
  • fallback_message_count int – 衍生回溯摘要文字以進行擷取和呈現時，所要使用的最近訊息數目。
  • max_relevant_results int – 要包含的已擷取長期記錄數上限。
  • max_recent_messages int – 要內嵌動詞的尾端原始訊息數目上限。
  • **kwargs ( 任一 ) – 保留供未來內容卡選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含以最近訊息為基礎之繫線相關資訊環境摘要的卡。
• 傳回類型： str

注意事項

這會使用繫線的預設搜尋範圍與 exact_thread_match=False，因此可以包含來自相同使用者 / 代理程式之其他繫線的相關記憶體。

範例

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card()
True

方法 get_context_card_async (非同步)

非同步傳回執行緒的類似 XML 內容卡。

• 參數：
  • fallback_message_count int – 衍生回溯摘要文字以進行擷取和呈現時，所要使用的最近訊息數目。
  • max_relevant_results int – 要包含的已擷取長期記錄數上限。
  • max_recent_messages int – 要內嵌動詞的尾端原始訊息數目上限。
  • **kwargs ( 任一 ) – 保留供未來內容卡選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含以最近訊息為基礎之繫線相關資訊環境摘要的卡。
• 傳回類型： str

方法 get_messages

回傳此討論串的已儲存訊息。

• 參數：
  • start int | None – 開始索引 (0-based)。與 end 一起省略時，會傳回最近連結的視窗。
  • end int | None – 結束索引 (不含)。省略時，會傳回最近訊息的連結視窗。傳送 None 或 -1 以明確向 start 要求所有訊息。
• 傳回：依時間順序排列的訊息。
• 傳回類型： list[ 訊息 ]

範例

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

方法 get_summary

傳回執行緒的最佳投入力摘要。

在 LLM 備份的實作可能執行遠端網路 I/O 時，偏好使用 get_summary_async。

• 參數：
  • except_last int – 要從摘要排除的最近訊息數目。
  • token_budget int – 軟權杖預算。省略時，會套用繫結的預設值。只有在格式化摘要超過 _estimate_tokens() 預估的預算時，正值才會截斷；傳回的文字會設成 int(token_budget * 3.5) 個字元。非正值會停用輸出界限。
  • **kwargs ( 任一 ) – 保留供未來摘要選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含摘要的助理訊息；如果執行緒沒有訊息，則傳回空白清單。
• 傳回類型： list[ 訊息 ]

範例

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
len(summary) >= 1
True

方法 get_summary_async (非同步)

非同步傳回執行緒的最佳投入力摘要。

• 參數：
  • except_last int – 要從摘要排除的最近訊息數目。
  • token_budget int – 軟權杖預算。省略時，會套用繫結的預設值。只有在格式化摘要超過 _estimate_tokens() 預估的預算時，正值才會截斷；傳回的文字會設成 int(token_budget * 3.5) 個字元。非正值會停用輸出界限。
  • **kwargs ( 任一 ) – 保留供未來摘要選項使用。未預期的關鍵字引數會產生 TypeError。
• 傳回：包含摘要的助理訊息；如果執行緒沒有訊息，則傳回空白清單。
• 傳回類型： list[ 訊息 ]

訊息

類別 oracleagentmemory.apis.thread.Message

基礎：object

• 參數：
  • 角色 str
  • 內容 str
  • 時間戳記 str | None
  • 中繼資料 dict[str, Any] | None
  • ID str | None