搜索

本页介绍了面向开发人员的范围限定帮助程序以及具体的 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 一起使用。如果希望默认操作，请忽略该字段。

范围

class 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。NOT_SET_MARKER 表示字段已省略，应使用特定于操作的默认值进行解析。显式 None 由特定于操作的规则保留和解释。

• 类型： str | None

thread_id

线程 ID。NOT_SET_MARKER 表示字段已省略，应使用特定于操作的默认值进行解析。显式 None 由特定于操作的规则保留和解释。

• 类型： str | None

class 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 中，None 在 exact_user_match 解析为 True 时仅针对未作用域的记录。

• 类型： str | None

座席标识

代理 ID。当解析的 exact_agent_match 值为 True 时，此 ID 将完全匹配，包括 None。如果为 False，则代理维不受约束。NOT_SET_MARKER 将替换为默认值，具体取决于使用作用域的操作。

• 类型： str | None

thread_id

线程 ID。当解析的 exact_thread_match 值为 True 时，此 ID 将完全匹配，包括 None。当它是 False 时，线程维不受约束。NOT_SET_MARKER 将替换为默认值，具体取决于使用作用域的操作。

• 类型： str | None

exact_user_ 匹配

是否与解析的 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

结果

class oracleagentmemory.core.OracleSearchResult

基础：SearchResult

Oracle 线程返回的搜索结果。

• 参数：
  • distance float- 与查询向量的距离（较小越好）。
  • record Record- 包含有关持久性条目的元数据信息的记录对象。
  • id str | None- 与存储的记录关联的可选标识符。

property（属性）content

• 返回类型： str
• 说明：返回匹配记录的主要文本内容。

property（属性）formatted_content

• 返回类型： str

• 说明：返回提示中使用的默认 XML 安全呈现。

• 返回：包括搜索结果的默认可见字段的 XML 安全呈现。
• 返回类型： str

property（属性）id

• 返回类型： str | None
• 说明：返回匹配记录的稳定标识符（如果可用）。

property（属性）metadata

• 返回类型： dict[str，Any] | None
• 说明：返回记录元数据（如果可用）。

property（属性）record

• 返回类型：记录
• 说明：返回匹配的记录。

返回的值可以是普通 Record 或 ScopedRecord 子类。在读取公共范围标识符之前，请使用 isinstance(result.record, ScopedRecord)。

property（属性）timestamp

• 返回类型： str | None
• 说明：返回记录时间戳（如果可用）。