Cerca

Questa pagina presenta gli strumenti di supporto per l'ambito rivolti agli sviluppatori insieme al tipo di risultati di ricerca Oracle concreto.

Risoluzione ambito

Per ogni campo di applicazione è possibile eseguire una delle tre operazioni riportate di seguito.

• omettere di utilizzare l'impostazione predefinita del layer API. Nelle firme Python e in SearchScope, questo stato omesso è rappresentato da NOT_SET_MARKER.
• specificare un ID concreto per utilizzare tale valore;
• specificare None per indicare che il record non ha ambito su tale dimensione. Ad esempio, agent_id=None indica che il record non è collegato a un agente.

Ogni record memorizzato dispone di tre campi di ambito indipendenti: user_id, agent_id e thread_id. Ogni campo può contenere un ID concreto o None.

Esempi:

• thread_id=None indica che il record non è collegato a un thread.
• agent_id=None indica che il record non è collegato a un agente.
• user_id="u1", agent_id=None, thread_id=None indica che il record è definito per l'utente u1, ma non per un agente o un thread specifico.

Le stesse regole di ambito si applicano sia alle API di ricerca sincrona che asincrona.

Nella tabella seguente, ID indica uno dei valori user_id, agent_id o thread_id insieme al relativo flag di corrispondenza esatta.

Risoluzione ambito di ricerca per livello API

Maiuscole/minuscole	thread.search()	OracleAgentMemory.search()	store.search()
ID omesso	Utilizza le impostazioni predefinite del thread: esatti user_id e agent_id, più l'attuale thread_id con exact_thread_match=False.	Utilizza le impostazioni predefinite del client. Il valore user_id omesso è stato rifiutato. agent_id e thread_id omessi rimangono ampi.	Utilizza i valori predefiniti dell'area di memorizzazione: ID=None e exact_*_match=False, in modo che la dimensione non venga filtrata.
Valore esplicito, incluso None + exact_*_match=False	La dimensione non è filtrata. I record il cui valore corrisponde a quello specificato possono essere classificati più in alto rispetto agli altri record.	Per user_id, rifiutato perché le ricerche client richiedono un ambito utente esatto esplicito. Per agent_id e thread_id, la dimensione non viene filtrata. I record il cui valore corrisponde a quello specificato possono essere classificati più in alto rispetto agli altri record.	La dimensione non è filtrata. I record il cui valore corrisponde a quello specificato possono essere classificati più in alto rispetto agli altri record.
ID esplicito + exact_*_match=True	Corrisponde esattamente a questo ID.	Corrisponde esattamente a questo ID.	Corrisponde esattamente a questo ID.
Esplicito None + exact_*_match=True	Corrisponde solo ai record senza ambito su tale dimensione.	Corrisponde solo ai record senza ambito su tale dimensione.	Corrisponde solo ai record senza ambito su tale dimensione.

Utilizzare None esplicito insieme a exact_*_match=True quando si desidera solo record senza ambito su tale dimensione e l'API lo consente. Omettere il campo quando si desidera che l'operazione sia predefinita.

Filtro stato ciclo di vita

Tutti i record persistenti hanno uno stato del ciclo di vita. La ricerca accetta include_invalid_results nelle API negozio, client e thread. Nelle API client e thread il valore predefinito è NOT_SET_MARKER, che risolve l'inclusione di record validi e non validi nei risultati della ricerca. L'API di memorizzazione di livello inferiore risolve le impostazioni predefinite booleane allo stesso funzionamento. Passare False per omettere i record con stato RecordStatus.INVALID.

Espansione grafico

Passare num_hops da 0 a 5 all'API di ricerca dell'area di memorizzazione, del client o del thread per collegare il contesto di memoria collegato a ogni risultato di memoria diretta. Traversal segue le relazioni in entrambe le direzioni, conserva l'orientamento della relazione memorizzata e restituisce una struttura di percorso più breve tramite la sequenza linked_results di ciascun record. Le corrispondenze di messaggi diretti, documenti e profili attore rimangono nel set di risultati classificato, ma non sono espanse nel grafico. In particolare, le descrizioni delle immagini ricercabili possono restituire i record delle immagini senza rendere DOCUMENT un vertice di collegamento alla memoria. L'ambito, i metadati, il tipo di record e i filtri di scadenza si applicano a ogni memoria collegata. include_invalid_results continua a controllare solo le corrispondenze di ricerca di livello superiore; non modifica le memorie collegate incluse. max_linked_results limita le memorie collegate totali collegate a ciascun risultato diretto in tutti i luppoli. Il valore predefinito è 100; passare 0 per omettere il contesto collegato.

Ambiti

classe oracleagentmemory.apis.scope.Scope

Basi: object

Rappresenta un ambito per l'inserimento o le ricerche di informazioni.

• Parametri:
  • ID_utente str | None
  • id_agente str | None
  • id_thread str | None

ID_utente

ID dell'utente finale. NOT_SET_MARKER indica che il campo è stato omesso e deve essere risolto in base all'impostazione predefinita specifica dell'operazione. L'espressione None esplicita viene conservata e interpretata dalle regole specifiche dell'operazione. Le API client di livello superiore, ad esempio OracleAgentMemory.search(), possono richiedere che l'ambito utente sia esplicito. In tali API, è possibile utilizzare None per indirizzare solo record con ambito non definito.

• Tipo: str | None

ID_agente

ID agente. NOT_SET_MARKER indica che il campo è stato omesso e deve essere risolto in base all'impostazione predefinita specifica dell'operazione. L'espressione None esplicita viene conservata e interpretata dalle regole specifiche dell'operazione.

• Tipo: str | None

ID_thread

ID thread. NOT_SET_MARKER indica che il campo è stato omesso e deve essere risolto in base all'impostazione predefinita specifica dell'operazione. L'espressione None esplicita viene conservata e interpretata dalle regole specifiche dell'operazione.

• Tipo: str | None

classe oracleagentmemory.apis.searchscope.SearchScope

Basi: Scope

Rappresenta l'ambito di una query di ricerca e quindi limita gli elementi che possono essere restituiti.

• Parametri:
  • ID_utente str | None
  • id_agente str | None
  • id_thread str | None
  • exact_user_match bool
  • exact_agent_match bool
  • corrispondenza_thread_exact bool

ID_utente

ID dell'utente finale. Quando il valore exact_user_match risolto è True, viene trovata una corrispondenza esatta con questo ID, incluso None. Quando si tratta di False, la dimensione utente non è vincolata. NOT_SET_MARKER viene sostituito da un valore predefinito specifico dell'operazione. Le API client di livello superiore, ad esempio OracleAgentMemory.search(), possono richiedere che l'ambito utente sia esplicito. In tali API, None è destinato solo ai record con ambito non definito quando exact_user_match viene risolto in True.

• Tipo: str | None

ID_agente

ID agente. Quando il valore exact_agent_match risolto è True, viene trovata una corrispondenza esatta con questo ID, incluso None. Quando è False, la dimensione agente non è vincolata. NOT_SET_MARKER viene sostituito da un valore predefinito a seconda dell'operazione che utilizza l'ambito.

• Tipo: str | None

ID_thread

ID thread. Quando il valore exact_thread_match risolto è True, viene trovata una corrispondenza esatta con questo ID, incluso None. Quando è False, la dimensione thread non è vincolata. NOT_SET_MARKER viene sostituito da un valore predefinito a seconda dell'operazione che utilizza l'ambito.

• Tipo: str | None

esatta_utente_corrispondenza

Indica se corrispondere esattamente al valore user_id risolto. True corrisponde esattamente, incluso None. False lascia la dimensione utente non vincolata. NOT_SET_MARKER viene sostituito da un valore predefinito a seconda dell'operazione. Le API client di livello superiore come OracleAgentMemory.search() potrebbero richiedere che rimangano True.

• Tipo: bolla

esatta_agente_corrispondenza

Indica se corrispondere esattamente al valore agent_id risolto. True corrisponde esattamente, incluso None. False lascia la dimensione agente non vincolata. NOT_SET_MARKER viene sostituito da un valore predefinito a seconda dell'operazione.

• Tipo: bolla

corrispondenza esatta_thread_

Indica se corrispondere esattamente al valore thread_id risolto. True corrisponde esattamente, incluso None. False lascia la dimensione thread non vincolata. NOT_SET_MARKER viene sostituito da un valore predefinito a seconda dell'operazione.

• Tipo: bolla

Configurazione ricerca

classe oracleagentmemory.core.MemorySearchConfig

Basi: ISearchConfig

Configurazione di base per il funzionamento post-ricerca della memoria.

• Parametri:
  • token_budget int | None
  • soft_token_budget int | None

Dimensione di destinazione facoltativa per l'output di ricerca formattato.

I risultati completi vengono mantenuti in ordine di classificazione fino al primo risultato che raggiunge o supera questo budget. Il primo risultato viene quindi mantenuto quando nessun hard token_budget ne impedisce la restituzione.

Limite assoluto facoltativo per la dimensione stimata dell'output di ricerca formattato.

I risultati completi vengono mantenuti in ordine di classificazione mentre la loro stima cumulativa corrisponde al budget. Se il primo risultato non si adatta, non vengono restituiti risultati.

classe oracleagentmemory.core.TopKMemorySearchConfig

Basi: _RerankingMemorySearchConfig

Configurazione di ricerca con un massimo fisso di risultati diretti.

• Parametri:
  • token_budget int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • max_results int

Numero massimo di risultati diretti recuperati prima della nuova classificazione.

classe oracleagentmemory.core.PruningEvaluationMode

Basi: str, Enum

Controlla il modo in cui vengono valutati estensivamente i risultati della ricerca durante l'eliminazione.

EXHAUSTIVE = "esaustivo"

Valuta i risultati di ogni candidato singolarmente. Ciò fornisce la valutazione più completa, ma ha la latenza più elevata e l'uso di LLM.

ESTESA = 'estesa'

Valuta una parte più ampia dei risultati prima di decidere quali conservare, a costo di latenza aggiuntiva e uso di LLM.

FAST = 'veloce'

Dai la priorità alla bassa latenza interrompendo la valutazione in anticipo quando è improbabile che ulteriori controlli modifichino i risultati che vengono conservati.

classe oracleagentmemory.core.PruningMemorySearchConfig

Basi: _RerankingMemorySearchConfig

Configurazione di ricerca che rimuove i risultati diretti meno rilevanti.

I limiti di risultato diretto vengono forniti su ogni chiamata di ricerca o di scheda contesto e applicati prima della nuova classificazione e della potatura.

• Parametri:
  • token_budget int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • modalità_valutazione PruningEvaluationMode
  • num_probe_points int
  • frazione_protetta float
  • pruner ILlm

Modalità di valutazione dei risultati della ricerca durante l'eliminazione.

Se omesso, viene utilizzato PruningEvaluationMode.FAST.

Numero di aree con risultati classificati valutate in modalità VELOCE o ESTESA.

Questo parametro non può essere impostato se evaluation_mode è PruningEvaluationMode.EXHAUSTIVE.

Frazione di risultati diretti più alti protetti dalla potatura.

Ad esempio, 0.1 protegge il 10% superiore dei risultati diretti.

LLM utilizzato per decidere quali risultati diretti rimuovere.

Risultati

classe oracleagentmemory.core.SearchResultFormatConfig

Basi: object

Controlla le opzioni di rendering portatili per risultati di ricerca.

Le implementazioni possono fornire a una sottoclasse opzioni di rendering aggiuntive.

• Parametri: include_invalid_results bool: indica se i record collegati non validi includono il relativo contenuto. Quando si omette False, vengono omesse solo le diramazioni non valide, mentre i record non validi in un percorso di un record valido conservano lo stato e il contesto del collegamento. Omettere di utilizzare True.

classe oracleagentmemory.core.OracleSearchResultFormatConfig

Basi: SearchResultFormatConfig

Controlla le opzioni di rendering dei risultati di ricerca di Oracle.

• Parametri:
  • show_thread_id bool: se includere l'identificativo del thread del record. Omettere di utilizzare False.
  • show_distance bool: se includere la rilevanza stimata. Omettere di utilizzare False.
  • show_timestamp bool: indica se includere gli indicatori orari dei record. Omettere di utilizzare True.
  • show_role bool: indica se includere i ruoli messaggio. Omettere di utilizzare True.
  • show_user_id bool: indica se includere gli identificativi utente dei record. Omettere di utilizzare False.
  • show_agent_id bool: indica se includere gli identificativi degli agenti dei record. Omettere di utilizzare False.
  • show_status bool: indica se includere gli stati del ciclo di vita dei record. Omettere di utilizzare True.
  • show_metadata bool: indica se includere i metadati del chiamante e il motivo dell'annullamento della convalida della memoria, se presenti. Ogni voce utilizza la chiave di metadati come tag XML e ne visualizza il valore come stringa. Omettere di utilizzare False.
  • include_invalid_results bool

classe oracleagentmemory.core.OracleSearchResult

Basi: SearchResult

Risultato della ricerca restituito da un thread Oracle.

• Parametri:
  • distance float: la distanza dal vettore di query (più piccolo è meglio).
  • record Record: oggetto record contenente le informazioni sui metadati relative alla voce persistente.
  • id str | None: identificativo facoltativo associato al record memorizzato.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None: risultati figlio facoltativi collegati al grafico. Ogni coppia contiene la RecordRelation memorizzata e il risultato raggiunto attraverso di essa.
  • format_config SearchResultFormatConfig – Opzioni di rendering predefinite usate da formatted_content e da format_content() quando non vengono fornite opzioni.

proprietà content

• Tipo restituito: str
• Descrizione: restituisce il contenuto testuale principale per il record corrispondente.

metodo format_content

Eseguire il rendering di questo risultato e del relativo contesto grafico come testo prompt sicuro per XML.

• Parametri: format_config SearchResultFormatConfig – Opzioni di rendering per questa chiamata. Omettere di utilizzare la configurazione predefinita del risultato. In una configurazione fornita, le opzioni omesse rientrano nelle opzioni corrispondenti in quella configurazione predefinita.
• Restituzioni: rendering sicuro per XML dei risultati.
• Tipo restituito: str

proprietà formatted_content

• Tipo restituito: str

• Descrizione: restituisce il rendering sicuro XML predefinito utilizzato nei prompt.

• Restituzioni: rendering sicuro per XML che utilizza la configurazione predefinita di questo risultato.
• Tipo restituito: str

proprietà id

• Tipo restituito: str

  Nessuno

• Descrizione: restituisce l'identificativo stabile del record corrispondente, se disponibile.

proprietà linked_results

• Tipo restituito: list[tuple[RecordRelation, SearchResult]]
• Descrizione: restituisce i risultati collegati nella relativa struttura ricorsiva del percorso più breve.

proprietà metadata

• Tipo restituito: dett[str, Any]

  Nessuno

• Descrizione: restituisce i metadati dei record, se disponibili.

proprietà record

• Tipo restituito: record
• Descrizione: restituisce il record corrispondente.

Il valore restituito può essere una classe secondaria Record normale o ScopedRecord. Utilizzare isinstance(result.record, ScopedRecord) prima di leggere gli identificativi di ambito pubblico.

proprietà status

• Tipo restituito: RecordStatus

  Nessuno

• Descrizione: restituisce lo stato del ciclo di vita per il record corrispondente.

proprietà timestamp

• Tipo restituito: str

  Nessuno

• Descrizione: restituire l'indicatore orario del record, se disponibile.