Rechercher

Cette page présente les aides à la définition de la portée destinées aux développeurs ainsi que le type de résultat de recherche Oracle concret.

Résolution de la portée

Pour chaque champ de portée, vous pouvez effectuer l'une des trois opérations suivantes :

• omettez-le pour utiliser la valeur par défaut de cette couche d'API. Dans les signatures Python et dans SearchScope, cet état omis est représenté par NOT_SET_MARKER.
• spécifier un ID concret pour utiliser cette valeur ;
• indiquez None pour indiquer que l'enregistrement n'a pas de portée sur cette dimension. Par exemple, agent_id=None signifie que l'enregistrement n'est pas lié à un agent.

Chaque enregistrement stocké comporte trois champs de portée indépendants : user_id, agent_id et thread_id. Chaque champ peut contenir un ID concret ou None.

Exemples :

• thread_id=None signifie que l'enregistrement n'est pas lié à un thread.
• agent_id=None signifie que l'enregistrement n'est pas lié à un agent.
• user_id="u1", agent_id=None, thread_id=None signifie que l'enregistrement est ciblé sur l'utilisateur u1, mais pas sur un agent ou un thread spécifique.

Les mêmes règles d'étendue s'appliquent aux API de recherche synchrone et asynchrone.

Dans le tableau ci-dessous, ID désigne l'un des éléments user_id, agent_id ou thread_id, ainsi que l'indicateur de correspondance exacte correspondant.

Résolution de portée de recherche par couche d'API

Dossier	thread.search()	OracleAgentMemory.search()	store.search()
ID omis	Utilise les valeurs par défaut de thread : user_id et agent_id exacts, plus thread_id en cours avec exact_thread_match=False.	Utilise les valeurs par défaut du client. user_id omis est rejeté. Omis agent_id et thread_id restent larges.	Utilise les valeurs par défaut de l'emplacement de stockage : ID=None et exact_*_match=False, de sorte que la dimension ne soit pas filtrée.
Valeur explicite, y compris None + exact_*_match=False	Cette dimension n'est pas filtrée. Les enregistrements dont la valeur correspond à celle indiquée peuvent être classés plus haut que les autres enregistrements.	Pour user_id, rejeté car les recherches client nécessitent une portée utilisateur précise explicite. Pour agent_id et thread_id, cette dimension n'est pas filtrée. Les enregistrements dont la valeur correspond à celle indiquée peuvent être classés plus haut que les autres enregistrements.	Cette dimension n'est pas filtrée. Les enregistrements dont la valeur correspond à celle indiquée peuvent être classés plus haut que les autres enregistrements.
ID explicite + exact_*_match=True	Correspond exactement à cet ID.	Correspond exactement à cet ID.	Correspond exactement à cet ID.
None et exact_*_match=True explicites	Correspond uniquement aux enregistrements non ciblés sur cette dimension.	Correspond uniquement aux enregistrements non ciblés sur cette dimension.	Correspond uniquement aux enregistrements non ciblés sur cette dimension.

Utilisez None explicite avec exact_*_match=True lorsque vous voulez que seuls les enregistrements ne soient pas inclus dans cette dimension et que l'API le permette. Omettez le champ lorsque vous voulez que l'opération soit définie par défaut.

Filtrage du statut du cycle de vie

Tous les enregistrements persistants ont un statut de cycle de vie. La recherche accepte include_invalid_results sur les API de stockage, de client et de thread. Sur les API client et de thread, la valeur par défaut est NOT_SET_MARKER, ce qui permet d'inclure les enregistrements valides et non valides dans les résultats de recherche. L'API de stockage de niveau inférieur résout sa valeur booléenne par défaut avec le même comportement. Transmettez False pour omettre les enregistrements dont le statut est RecordStatus.INVALID.

Extension de graphique

Transmettez num_hops de 0 à 5 à l'API de recherche de stockage, de client ou de thread pour attacher le contexte de mémoire lié à chaque résultat de mémoire directe. La traversée suit les relations dans les deux sens, conserve l'orientation de la relation stockée et renvoie une arborescence à chemin le plus court dans la séquence linked_results de chaque enregistrement. Les correspondances de message direct, de document et de profil d'acteur restent dans l'ensemble de résultats classé, mais ne sont pas développées dans le graphique. En particulier, les descriptions d'image pouvant faire l'objet d'une recherche peuvent renvoyer des enregistrements d'image sans faire de DOCUMENT un sommet de liaison mémoire. Les filtres de portée, de métadonnées, de type d'enregistrement et d'expiration s'appliquent à chaque mémoire liée. include_invalid_results continue de contrôler uniquement les correspondances de recherche de niveau supérieur ; il ne modifie pas les mémoires liées incluses. max_linked_results limite le nombre total de mémoires liées attachées à chaque résultat direct sur tous les sauts. La valeur par défaut est 100. Transmettez 0 pour omettre le contexte lié.

Portées

classe oracleagentmemory.apis.scope.Scope

Bases : object

Représente une portée pour l'insertion ou la recherche d'informations.

• Paramètres:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None

user_id

ID d'utilisateur final. NOT_SET_MARKER signifie que le champ a été omis et doit être résolu par la valeur par défaut propre à l'opération. L'expression None explicite est conservée et interprétée par les règles propres à l'opération. Les API client de niveau supérieur telles que OracleAgentMemory.search() peuvent exiger que la portée utilisateur soit explicite. Dans ces API, None peut être utilisé pour cibler uniquement les enregistrements non ciblés.

• Type : str | None

agent_id

ID d'agent. NOT_SET_MARKER signifie que le champ a été omis et doit être résolu par la valeur par défaut propre à l'opération. L'expression None explicite est conservée et interprétée par les règles propres à l'opération.

• Type : str | None

id_thread

ID de thread. NOT_SET_MARKER signifie que le champ a été omis et doit être résolu par la valeur par défaut propre à l'opération. L'expression None explicite est conservée et interprétée par les règles propres à l'opération.

• Type : str | None

classe oracleagentmemory.apis.searchscope.SearchScope

Bases : Scope

Représente la portée d'une requête de recherche et limite donc ce qui peut être renvoyé.

• Paramètres:
  • 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 d'utilisateur final. Lorsque la valeur exact_user_match résolue est True, cet ID correspond exactement, y compris None. Lorsque la valeur est False, la dimension utilisateur n'est pas contrainte. NOT_SET_MARKER est remplacé par une valeur par défaut propre à l'opération. Les API client de niveau supérieur telles que OracleAgentMemory.search() peuvent exiger que la portée utilisateur soit explicite. Dans ces API, None cible uniquement les enregistrements non ciblés lorsque exact_user_match est résolu en True.

• Type : str | None

agent_id

ID d'agent. Lorsque la valeur exact_agent_match résolue est True, cet ID correspond exactement, y compris None. Lorsque la valeur est False, la dimension d'agent n'est pas contrainte. NOT_SET_MARKER est remplacé par une valeur par défaut en fonction de l'opération utilisant la portée.

• Type : str | None

id_thread

ID de thread. Lorsque la valeur exact_thread_match résolue est True, cet ID correspond exactement, y compris None. Lorsque la valeur est False, la dimension de thread n'est pas contrainte. NOT_SET_MARKER est remplacé par une valeur par défaut en fonction de l'opération utilisant la portée.

• Type : str | None

exact_user_match

Indique si la correspondance doit être exacte avec le fichier user_id résolu. True correspond exactement, y compris None. False laisse la dimension utilisateur sans contrainte. NOT_SET_MARKER est remplacé par une valeur par défaut en fonction de l'opération. Les API client de niveau supérieur telles que OracleAgentMemory.search() peuvent exiger qu'elles restent True.

• Type : booléen

exact_agent_match

Indique si la correspondance doit être exacte avec le fichier agent_id résolu. True correspond exactement, y compris None. False laisse la dimension d'agent sans contrainte. NOT_SET_MARKER est remplacé par une valeur par défaut en fonction de l'opération.

• Type : booléen

correspondance_thread_exact

Indique si la correspondance doit être exacte avec le fichier thread_id résolu. True correspond exactement, y compris None. False laisse la dimension de thread sans contrainte. NOT_SET_MARKER est remplacé par une valeur par défaut en fonction de l'opération.

• Type : booléen

Configuration de la recherche

classe oracleagentmemory.core.MemorySearchConfig

Bases : ISearchConfig

Configuration de base pour le comportement après la recherche de mémoire.

• Paramètres:
  • token_budget int | None
  • soft_token_budget int | None

Taille cible facultative pour la sortie de recherche formatée.

Les résultats complets sont classés par ordre chronologique jusqu'au premier résultat qui atteint ou dépasse ce budget. Le premier résultat est donc conservé lorsqu'aucun élément token_budget fixe ne l'empêche d'être renvoyé.

Limite fixe facultative pour la taille estimée de la sortie de recherche formatée.

Les résultats complets sont classés dans l'ordre tandis que leur estimation cumulée correspond au budget. Si le premier résultat ne convient pas, aucun résultat n'est renvoyé.

classe oracleagentmemory.core.TopKMemorySearchConfig

Bases : _RerankingMemorySearchConfig

Configuration de recherche avec un maximum fixe de résultats directs.

• Paramètres:
  • token_budget int | None
  • soft_token_budget int | None
  • banque IReranker | None
  • reranker_max_candidates int
  • max_results int

Nombre maximum de résultats directs récupérés avant le reclassement.

classe oracleagentmemory.core.PruningEvaluationMode

Bases : str, Enum

Contrôle l'évaluation approfondie des résultats de recherche lors de l'élagage.

EXHAUSTIVE = 'exhaustif'

Evaluez chaque résultat candidat individuellement. Cela fournit l'évaluation la plus complète, mais présente la latence et l'utilisation de LLM les plus élevées.

EXTENDED = 'EXTENDED'

Evaluez une plus grande partie des résultats avant de décider lesquels conserver, au prix d'une latence supplémentaire et d'une utilisation de LLM.

RAPIDE = 'rapide'

Donnez la priorité à la faible latence en arrêtant l'évaluation plus tôt lorsque d'autres vérifications sont peu susceptibles de modifier les résultats retenus.

classe oracleagentmemory.core.PruningMemorySearchConfig

Bases : _RerankingMemorySearchConfig

Configuration de recherche qui supprime les résultats directs moins pertinents.

Des limites de résultats directs sont fournies sur chaque appel de recherche ou de carte de contexte et appliquées avant le reclassement et l'élagage.

• Paramètres:
  • token_budget int | None
  • soft_token_budget int | None
  • banque IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • pruner ILlm

Nombre de résultats de recherche évalués lors de l'élagage.

Lorsqu'elle est omise, PruningEvaluationMode.FAST est utilisé.

Nombre de régions classées évaluées en mode FAST ou EXTENDED.

Ce paramètre ne peut pas être défini lorsque evaluation_mode est PruningEvaluationMode.EXHAUSTIVE.

Fraction des résultats directs les plus élevés protégés de l'élagage.

Par exemple, 0.1 protège les 10 % principaux des résultats directs.

Le modèle de langage (LLM) déterminait les résultats directs à supprimer.

Résultats

classe oracleagentmemory.core.SearchResultFormatConfig

Bases : object

Contrôlez les options de rendu portables des résultats de recherche.

Les implémentations peuvent fournir une sous-classe avec des options d'affichage supplémentaires.

• Paramètres : include_invalid_results bool – Indique si les enregistrements liés non valides incluent leur contenu. Lorsque False, les branchements non valides uniquement sont omis, tandis que les enregistrements non valides sur un chemin d'accès à un enregistrement valide conservent leur statut et leur contexte de lien. Omettez d'utiliser True.

classe oracleagentmemory.core.OracleSearchResultFormatConfig

Bases : SearchResultFormatConfig

Contrôler les options d'affichage des résultats de recherche Oracle.

• Paramètres:
  • show_thread_id bool – Indique si l'identificateur de thread de l'enregistrement doit être inclus. Omettez d'utiliser False.
  • show_distance bool – Indique si la pertinence estimée doit être incluse. Omettez d'utiliser False.
  • show_timestamp bool – Indique si les horodatages des enregistrements doivent être inclus. Omettez d'utiliser True.
  • show_role bool : indique si les rôles de message doivent être inclus. Omettez d'utiliser True.
  • show_user_id bool – Indique s'il faut inclure des identifiants d'utilisateur d'enregistrement. Omettez d'utiliser False.
  • show_agent_id bool – Indique si les identificateurs d'agent d'enregistrement doivent être inclus. Omettez d'utiliser False.
  • show_status bool – Indique si les statuts de cycle de vie des enregistrements doivent être inclus. Omettez d'utiliser True.
  • show_metadata bool : indique si les métadonnées de l'appelant et le motif d'invalidation de la mémoire doivent être inclus, le cas échéant. Chaque entrée utilise sa clé de métadonnées en tant que balise XML et affiche sa valeur en tant que chaîne. Omettez d'utiliser False.
  • include_invalid_results bool

classe oracleagentmemory.core.OracleSearchResult

Bases : SearchResult

Résultat de la recherche renvoyé par un thread Oracle.

• Paramètres:
  • distance float : distance par rapport au vecteur de requête (plus petite est préférable).
  • record Record – Objet d'enregistrement contenant les informations de métadonnées relatives à l'entrée persistante.
  • id str | None : identificateur facultatif associé à l'enregistrement stocké.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None : résultats enfant liés à un graphique facultatifs. Chaque paire contient la relation d'enregistrement stockée et le résultat obtenu.
  • format_config SearchResultFormatConfig – Options de rendu par défaut utilisées par formatted_content et par format_content() lorsqu'aucune option n'est fournie.

propriété content

• Type de retour : str
• Description : renvoie le contenu textuel principal de l'enregistrement mis en correspondance.

méthode format_content

Affichez ce résultat et son contexte graphique en tant que texte d'invite sécurisé au format XML.

• Paramètres : format_config SearchResultFormatConfig – Options de rendu pour cet appel. Omettez d'utiliser la configuration par défaut de ce résultat. Dans une configuration fournie, les options omises reprennent les options correspondantes de cette configuration par défaut.
• Renvoie : affichage des résultats avec sécurité XML.
• Type de retour : str

propriété formatted_content

• Type de retour : str

• Description : renvoie le rendu sécurisé au format XML par défaut utilisé dans les invites.

• Renvoie : affichage XML sécurisé qui utilise la configuration par défaut de ce résultat.
• Type de retour : str

propriété id

• Type de retour : str

  Aucun

• Description : Renvoie l'identifiant stable de l'enregistrement mis en correspondance, lorsqu'il est disponible.

propriété linked_results

• Type de retour : list[tuple[RecordRelation, SearchResult]]
• Description : renvoie les résultats liés dans leur arborescence récursive à chemin le plus court.

propriété metadata

• Type de retour : dict[str, Any]

  Aucun

• Description : renvoie les métadonnées d'enregistrement, le cas échéant.

propriété record

• Type renvoyé : Enregistrement
• Description : renvoie l'enregistrement correspondant.

La valeur renvoyée peut être une sous-classe Record ou ScopedRecord simple. Utilisez isinstance(result.record, ScopedRecord) avant de lire les identificateurs de portée publique.

propriété status

• Type de retour : RecordStatus

  Aucun

• Description : renvoie le statut du cycle de vie de l'enregistrement mis en correspondance.

propriété timestamp

• Type de retour : str

  Aucun

• Description : renvoie l'horodatage de l'enregistrement, le cas échéant.