繫線數目

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

Oracle 執行緒

類別 oracleagentmemory.core.OracleThread

基本：IThread

由 Oracle 商店支援的執行緒。

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

注意事項

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

建立新的執行緒處理。

• 參數：
  • store OracleMemoryStore – 用來保存內嵌記錄的共用存放區後端。
  • thread_id str – 繫線 ID。若未提供，則會產生 UUID。
  • user_id str – 與執行緒關聯的使用者識別碼。如果省略，則會產生 UUID。
  • agent_id str – 與繫線關聯的代理程式 ID。如果省略，則會產生 UUID。
  • 中繼資料 dict[str, Any] | None – 與執行緒相關聯的選擇性類似 JSON 的中繼資料。
  • persist_messages_in_config bool – _to_config 是否應包含最近的原始訊息快照。針對使用資料庫存放區的繫線自動設為 False，以避免透過繫線組態匯出訊息表格內容。
  • LLM ILlm | None – 選用的 LLM 轉接器，用於記憶體擷取與環境定義摘要更新。提供時，add_messages 會從每個新增的訊息擷取相關記憶體，並將它們儲存為輸入的記憶體記錄 ("memory"、"guideline"、"fact" 或 "preference")。
  • memory_extraction_window int – 擷取期間要提供作為 LLM 相關資訊環境的最近訊息數目 (包括新新增的訊息)。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。預設為 -1。
  • context_summary_update_frequency int – 應更新擷取相關資訊環境摘要的訊息數目。設為 -1，即可使用整批新增的訊息，針對每一 add_messages 呼叫彙總一次。預設為 -1。
  • memory_extraction_frequency int – 觸發記憶體擷取的訊息數目。設為 -1，只會使用新增訊息的完整批次，擷取每個 add_messages 呼叫一次。
  • memory_extraction_token_limit int – 用於記憶體擷取和執行摘要更新的 LLM 提示大小上限 (記號)。較長的提示會被截斷。若為負數或 0，則會停用提示截斷。
  • context_card_token_limit int – 用於相關資訊環境卡摘要的 LLM 提示大小上限 (記號)。預設為 100_000 記號。較長的提示會被截斷。若為負數或 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 完全符合此繫線的類似記憶體記錄 (memory、guideline、fact、preference) 才會被刪除。
• 傳回數：刪除的記錄數 (0 或 1)。當識別碼不存在或屬於其他執行緒時，傳回 0。
• 傳回類型：整數

範例

thread.delete_memory("456")
0

方法 delete_message

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

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

注意事項

刪除訊息只會移除原始訊息記錄。衍生的記憶體不會被刪除，因為擷取的記憶體不會保留每個訊息的來源，因此它們仍然可以搜尋或仍會影響內容卡輸出。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。

範例

thread.delete_message("123")
0

方法 get_context_card

傳回繫線的相關資訊環境卡物件。

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

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

注意事項

這會使用繫線的預設搜尋範圍與 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().content
True

方法 get_context_card_async (非同步)

非同步傳回執行緒的環境定義卡物件。

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

方法 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。
• 傳回：包含合成繫線摘要文字的摘要物件。
• 傳回類型：OracleSummary

範例

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

方法 get_summary_async (非同步)

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

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

注意：delete_message() 只會刪除原始訊息資料列。衍生的記憶卡仍可搜尋或出現在內容卡中。使用 OracleAgentMemory.delete_thread() 可將繫線與其相關的訊息和記憶體一起刪除。

訊息

類別 oracleagentmemory.apis.thread.Message

基礎：object

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

內容卡

類別 oracleagentmemory.apis.contextcard.ContextCard

基本：ABC

繫線 API 傳回的抽象相關資訊環境卡物件。

property content (摘要)

• 傳回類型： str
• 描述：傳回轉譯的內容卡文字。

類別 oracleagentmemory.core.contextcard.OracleContextCard

基本：ContextCard

Oracle 執行緒傳回的內容卡。

• 參數：
  • summary str – 卡片中內嵌的摘要文字。
  • 主題 Sequence[str] | None – 與執行緒關聯的選擇性擷取主題。
  • relevant_results Sequence[SearchResult] | None – 卡片中包含的選擇性擷取持久記錄。
  • recent_messages Sequence[Message] | None – 可選擇將最近的原始訊息轉譯到卡片中。
  • message_format str – 呈現 recent_messages 時使用的內部範本。

特性 content

• 傳回類型： str

• 描述：傳回轉譯的內容卡文字。

• 傳回：類似 XML 的轉譯相關資訊環境卡文字，適用於提示組合。
• 傳回類型： str

範例

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

特性 formatted_content

• 傳回類型： str

• 描述：傳回用於提示建立流程的已轉譯內容卡文字。

• 傳回： 類似 XML 的轉譯內容卡文字。
• 傳回類型： str

範例

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

摘要

類別 oracleagentmemory.apis.summary.Summary

基本：ABC

繫線 API 傳回的抽象繫線摘要物件。

property content (摘要)

• 傳回類型： str
• 描述：傳回合成摘要文字。

類別 oracleagentmemory.core.summary.OracleSummary

基本：Summary

Oracle 執行緒傳回的摘要。

• 參數： content str – 從繫線記錄合成的摘要文字。

範例

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

特性 content

• 傳回類型： str

• 描述：傳回合成摘要文字。

• 傳回：執行緒的摘要文字。
• 傳回類型： str

範例

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

特性 formatted_content

• 傳回類型： str

• 描述：傳回用於提示建立流程的轉譯摘要文字。

• 傳回：呈現的摘要文字。
• 傳回類型： str

範例

OracleSummary(content="Thread recap").formatted_content
'Thread recap'