Buscar

Esta página presenta los ayudantes de ámbito orientados al desarrollador junto con el tipo concreto de resultados de búsqueda de Oracle.

Resolución de ámbito

Para cada campo de ámbito, puede realizar una de estas tres acciones:

• omitirlo para utilizar el valor por defecto de esa capa de API. En las firmas de Python y en SearchScope, este estado omitido se representa mediante NOT_SET_MARKER.
• especificar una identificación concreta para utilizar ese valor;
• especifique None para indicar que el registro no tiene ámbito en esa dimensión. Por ejemplo, agent_id=None significa que el registro no está vinculado a un agente.

Cada registro almacenado tiene tres campos de ámbito independientes: user_id, agent_id y thread_id. Cada campo puede contener un ID concreto o None.

Ejemplos:

• thread_id=None significa que el registro no está vinculado a un thread.
• agent_id=None significa que el registro no está vinculado a un agente.
• user_id="u1", agent_id=None, thread_id=None significa que el registro tiene un ámbito para el usuario u1, pero no para ningún agente o thread específico.

Las mismas reglas de ámbito se aplican a las API de búsqueda síncronas y asíncronas.

En la tabla siguiente, ID significa cualquiera de user_id, agent_id o thread_id junto con su indicador de coincidencia exacta correspondiente.

Resolución del ámbito de búsqueda por capa de API

Caso	thread.search()	OracleAgentMemory.search()	store.search()
ID omitido	Utiliza los valores por defecto del thread: user_id y agent_id exactos, además de thread_id actual con exact_thread_match=False.	Utiliza los valores predeterminados del cliente. Se ha rechazado user_id omitido. Se han omitido agent_id y thread_id.	Utiliza los valores por defecto del almacén: ID=None y exact_*_match=False, para que la dimensión no se filtre.
Valor explícito, incluidos None + exact_*_match=False	Esta dimensión no se filtra. Los registros cuyo valor coincida con el especificado pueden tener una clasificación superior a la de otros registros.	Para user_id, se ha rechazado porque las búsquedas de cliente requieren un ámbito de usuario exacto explícito. Para agent_id y thread_id, esa dimensión no se filtra. Los registros cuyo valor coincida con el especificado pueden tener una clasificación superior a la de otros registros.	Esta dimensión no se filtra. Los registros cuyo valor coincida con el especificado pueden tener una clasificación superior a la de otros registros.
ID explícito + exact_*_match=True	Coincide exactamente con ese ID.	Coincide exactamente con ese ID.	Coincide exactamente con ese ID.
None + exact_*_match=True explícitos	Solo coincide con los registros sin ámbito de esa dimensión.	Solo coincide con los registros sin ámbito de esa dimensión.	Solo coincide con los registros sin ámbito de esa dimensión.

Utilice None explícito junto con exact_*_match=True cuando solo desee que los registros sin ámbito de esa dimensión y la API lo permitan. Omita el campo cuando desee que la operación sea la predeterminada.

Filtrado de estado de ciclo de vida

Todos los registros guardados tienen un estado de ciclo de vida. La búsqueda acepta include_invalid_results en las API de almacén, cliente y thread. En las API de cliente y thread, el valor por defecto es NOT_SET_MARKER, que se resuelve para incluir registros válidos y no válidos en los resultados de búsqueda. La API de tienda de nivel inferior resuelve su valor por defecto booleano con el mismo comportamiento. Transfiera False para omitir registros cuyo estado sea RecordStatus.INVALID.

Ampliación de grafos

Transfiera num_hops de 0 a 5 a la API de búsqueda de almacén, cliente o thread para asociar el contexto de memoria enlazada a cada resultado de memoria directa. Traversal sigue las relaciones en cualquier dirección, conserva la orientación de la relación almacenada y devuelve un árbol de ruta más corta a través de la secuencia linked_results de cada registro. Las coincidencias de mensaje directo, documento y perfil de actor permanecen en el juego de resultados clasificados, pero no se amplían mediante gráficos. En particular, las descripciones de imágenes que se pueden buscar pueden devolver registros de imágenes sin convertir DOCUMENT en un vértice de enlace de memoria. Los filtros de ámbito, metadatos, tipo de registro y caducidad se aplican a cada memoria enlazada. include_invalid_results sigue controlando solo las coincidencias de búsqueda de nivel superior; no cambia las memorias enlazadas que se incluyen. max_linked_results limita el total de memorias enlazadas asociadas a cada resultado directo en todos los saltos. El valor por defecto es 100; transfiera 0 para omitir el contexto enlazado.

Ámbitos

clase oracleagentmemory.apis.scope.Scope

Bases: object

Representa un ámbito para la inserción o búsqueda de información.

• Parámetros:
  • ID_usuario str | None
  • agent_id str | None
  • thread_id str | None

user_id (ID de usuario)

ID del usuario final. NOT_SET_MARKER significa que el campo se ha omitido y se debe resolver mediante el valor por defecto específico de la operación. None explícito se conserva e interpreta mediante las reglas específicas de la operación. Las API de cliente de nivel superior, como OracleAgentMemory.search(), pueden requerir que el ámbito de usuario sea explícito. En esas API, None se puede utilizar solo para dirigir registros sin ámbito.

• Tipo: str | Ninguno

agent_id (ID de agente)

ID de Agente. NOT_SET_MARKER significa que el campo se ha omitido y se debe resolver mediante el valor por defecto específico de la operación. None explícito se conserva e interpreta mediante las reglas específicas de la operación.

• Tipo: str | Ninguno

ID_subproceso

Identificador de Thread. NOT_SET_MARKER significa que el campo se ha omitido y se debe resolver mediante el valor por defecto específico de la operación. None explícito se conserva e interpreta mediante las reglas específicas de la operación.

• Tipo: str | Ninguno

clase oracleagentmemory.apis.searchscope.SearchScope

Bases: Scope

Representa el ámbito de una consulta de búsqueda y, por lo tanto, restringe lo que se puede devolver.

• Parámetros:
  • ID_usuario 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 de usuario)

ID del usuario final. Cuando el valor exact_user_match resuelto es True, este ID coincide exactamente, incluido None. Cuando es False, la dimensión de usuario no tiene restricciones. NOT_SET_MARKER se sustituye por un valor por defecto específico de la operación. Las API de cliente de nivel superior, como OracleAgentMemory.search(), pueden requerir que el ámbito de usuario sea explícito. En esas API, None solo tiene como destino registros sin ámbito cuando exact_user_match se resuelve en True.

• Tipo: str | Ninguno

agent_id (ID de agente)

ID de Agente. Cuando el valor exact_agent_match resuelto es True, este ID coincide exactamente, incluido None. Cuando es False, la dimensión de agente no tiene restricciones. NOT_SET_MARKER se sustituye por un valor por defecto según la operación que utilice el ámbito.

• Tipo: str | Ninguno

ID_subproceso

Identificador de Thread. Cuando el valor exact_thread_match resuelto es True, este ID coincide exactamente, incluido None. Cuando es False, la dimensión de thread no tiene restricciones. NOT_SET_MARKER se sustituye por un valor por defecto según la operación que utilice el ámbito.

• Tipo: str | Ninguno

exact_user_match

Si coincide exactamente con el user_id resuelto. True coincide exactamente, incluido None. False deja la dimensión de usuario sin restricciones. NOT_SET_MARKER se sustituye por un valor por defecto según la operación. Las API de cliente de nivel superior, como OracleAgentMemory.search(), pueden necesitar que esto siga siendo True.

• Tipo: bool

exacto_agente_coincidencia

Si coincide exactamente con el agent_id resuelto. True coincide exactamente, incluido None. False deja la dimensión de agente sin restricciones. NOT_SET_MARKER se sustituye por un valor por defecto según la operación.

• Tipo: bool

exact_thread_match

Si coincide exactamente con el thread_id resuelto. True coincide exactamente, incluido None. False deja la dimensión de thread sin restricciones. NOT_SET_MARKER se sustituye por un valor por defecto según la operación.

• Tipo: bool

Configuración de Búsqueda

clase oracleagentmemory.core.MemorySearchConfig

Bases: ISearchConfig

Configuración básica para el comportamiento posterior a la búsqueda de la memoria.

• Parámetros:
  • presupuesto_token int | None
  • soft_token_budget int | None

Tamaño de destino opcional para la salida de búsqueda con formato.

Los resultados completos se mantienen en orden de clasificación hasta el primer resultado que alcanza o supera este presupuesto. Por lo tanto, el primer resultado se conserva cuando no hay token_budget duro que impida que se devuelva.

Límite obligatorio opcional para el tamaño estimado de la salida de búsqueda formateada.

Los resultados completos se mantienen en orden de clasificación, mientras que su estimación acumulada se ajusta al presupuesto. Si el primer resultado no encaja, no se devolverá ningún resultado.

clase oracleagentmemory.core.TopKMemorySearchConfig

Bases: _RerankingMemorySearchConfig

Configuración de búsqueda con un máximo fijo de resultados directos.

• Parámetros:
  • presupuesto_token int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • max_results int

Número máximo de resultados directos recuperados antes de la nueva versión.

clase oracleagentmemory.core.PruningEvaluationMode

Bases: str, Enum

Controla en qué medida se evalúan los resultados de búsqueda durante la depuración.

EXHAUSTIVE = 'exhaustivo'

Evaluar cada resultado de candidato individualmente. Esto proporciona la evaluación más completa, pero tiene la latencia y el uso de LLM más altos.

EXTENDED = 'EXTENDED' (Extendido)

Evalúe una parte más amplia de los resultados antes de decidir cuáles retener, a costa de latencia adicional y uso del LLM.

RÁPIDO = 'rápido'

Priorice la baja latencia deteniendo la evaluación antes de tiempo cuando sea poco probable que cambien los resultados que se conservan.

clase oracleagentmemory.core.PruningMemorySearchConfig

Bases: _RerankingMemorySearchConfig

Configuración de búsqueda que elimina los resultados directos menos relevantes.

Los límites de resultado directo se proporcionan en cada búsqueda o llamada de tarjeta de contexto y se aplican antes de volver a ordenar y podar.

• Parámetros:
  • presupuesto_token int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • pruner ILlm

Cuánto se evalúan los resultados de búsqueda durante la poda.

Cuando se omite, se utiliza PruningEvaluationMode.FAST.

Número de regiones de resultados clasificados evaluadas en modo FAST o EXTENDED.

Este parámetro no se puede definir cuando evaluation_mode es PruningEvaluationMode.EXHAUSTIVE.

Fracción de los resultados directos de mayor rango protegidos de la poda.

Por ejemplo, 0.1 protege el 10% superior de los resultados directos.

El LLM se utiliza para decidir qué resultados directos eliminar.

Resultados

clase oracleagentmemory.core.SearchResultFormatConfig

Bases: object

Controle las opciones de representación de resultados de búsqueda portátiles.

Las implantaciones pueden proporcionar una subclase con opciones de presentación adicionales.

• Parámetros: include_invalid_results bool: indica si los registros enlazados no válidos incluyen su contenido. Cuando False, se omiten bifurcaciones de sólo no válidas, mientras que los registros no válidos de una ruta a un registro válido conservan su estado y contexto de enlace. Omita utilizar True.

clase oracleagentmemory.core.OracleSearchResultFormatConfig

Bases: SearchResultFormatConfig

Controlar las opciones de presentación de resultados de búsqueda de Oracle.

• Parámetros:
  • show_thread_id bool: indica si se debe incluir el identificador de subproceso del registro. Omita utilizar False.
  • show_distance bool: indica si se debe incluir la relevancia estimada. Omita utilizar False.
  • show_timestamp bool: indica si se deben incluir registros de hora. Omita utilizar True.
  • show_role bool: indica si se deben incluir roles de mensajes. Omita utilizar True.
  • show_user_id bool: indica si se deben incluir identificadores de usuario de registro. Omita utilizar False.
  • show_agent_id bool: indica si se deben incluir identificadores de agente de registro. Omita utilizar False.
  • show_status bool: indica si se deben incluir los estados del ciclo de vida del registro. Omita utilizar True.
  • show_metadata bool: indica si se deben incluir los metadatos del emisor de llamada y el motivo de invalidación de la memoria, cuando estén presentes. Cada entrada utiliza su clave de metadatos como etiqueta XML y representa su valor como una cadena. Omita utilizar False.
  • include_invalid_results bool

clase oracleagentmemory.core.OracleSearchResult

Bases: SearchResult

Resultado de búsqueda devuelto por un thread de Oracle.

• Parámetros:
  • distance float: distancia del vector de consulta (más pequeño es mejor).
  • record Record: objeto de registro que contiene la información de metadatos sobre la entrada guardada.
  • id str | None: identificador opcional asociado con el registro almacenado.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None: resultados secundarios opcionales vinculados a gráficos. Cada par contiene la RecordRelation almacenada y el resultado alcanzado a través de ella.
  • format_config SearchResultFormatConfig: opciones de presentación predeterminadas utilizadas por formatted_content y por format_content() cuando no se proporcionan opciones.

propiedad content

• Tipo de devolución: str
• Descripción: devuelve el contenido textual principal del registro coincidente.

método format_content

Representar este resultado y su contexto de gráfico como texto de petición de datos seguro para XML.

• Parámetros: format_config SearchResultFormatConfig: opciones de representación para esta llamada. Omita utilizar la configuración predeterminada de este resultado. En una configuración proporcionada, las opciones omitidas vuelven a las opciones correspondientes en esa configuración predeterminada.
• Devoluciones: representación de resultados segura para XML.
• Tipo de devolución: str

propiedad formatted_content

• Tipo de devolución: str

• Descripción: devuelve la representación segura de XML por defecto utilizada en las peticiones de datos.

• Devoluciones: representación a prueba de XML que utiliza la configuración por defecto de este resultado.
• Tipo de devolución: str

propiedad id

• Tipo de devolución: str

  Ninguno

• Descripción: devuelve el identificador estable del registro coincidente, cuando esté disponible.

propiedad linked_results

• Tipo de devolución: list[tuple[RecordRelation, SearchResult]]
• Descripción: devuelve los resultados enlazados en su árbol recursivo de ruta más corta.

propiedad metadata

• Tipo de devolución: dict[str, Any]

  Ninguno

• Descripción: devuelve los metadatos del registro, si están disponibles.

propiedad record

• Tipo de valor devuelto: Registro
• Descripción: devuelve el registro coincidente.

El valor devuelto puede ser una subclase Record o ScopedRecord sin formato. Utilice isinstance(result.record, ScopedRecord) antes de leer los identificadores de ámbito público.

propiedad status

• Tipo de devolución: RecordStatus

  Ninguno

• Descripción: devuelve el estado del ciclo de vida del registro coincidente.

propiedad timestamp

• Tipo de devolución: str

  Ninguno

• Descripción: devuelve el registro de hora, si está disponible.