Suchen

Auf dieser Seite werden die Scoping-Helfer für Entwickler zusammen mit dem konkreten Oracle-Suchergebnistyp angezeigt.

Umfangsauflösung

Für jedes Geltungsbereichsfeld können Sie eine der drei folgenden Aktionen ausführen:

• Lassen Sie es aus, um den Standard dieser API-Schicht zu verwenden. In Python-Signaturen und in SearchScope wird dieser ausgelassene Status durch NOT_SET_MARKER dargestellt.
• konkrete ID für die Verwendung dieses Wertes angeben;
• Geben Sie None an, damit der Datensatz für diese Dimension nicht kopiert wird. Beispiel: agent_id=None bedeutet, dass der Datensatz nicht an einen Agent gebunden ist.

Jeder gespeicherte Datensatz verfügt über drei unabhängige Geltungsbereichsfelder: user_id, agent_id und thread_id. Jedes Feld kann eine konkrete ID oder None enthalten.

Beispiele:

• thread_id=None bedeutet, dass der Datensatz nicht an einen Thread gebunden ist.
• agent_id=None bedeutet, dass der Datensatz nicht an einen Agent gebunden ist.
• user_id="u1", agent_id=None, thread_id=None bedeutet, dass der Datensatz für den Benutzer u1, jedoch nicht für einen bestimmten Agent oder Thread gilt.

Dieselben Geltungsbereichsregeln gelten sowohl für synchrone als auch für asynchrone Such-APIs.

In der folgenden Tabelle bedeutet ID eine beliebige Zahl von user_id, agent_id oder thread_id zusammen mit dem entsprechenden Kennzeichen "Exact-Match".

Suchumfangsauflösung nach API-Layer

Ticket	thread.search()	OracleAgentMemory.search()	store.search()
ID ausgelassen	Verwendet die Threadstandardwerte: exakte user_id und agent_id sowie die aktuelle thread_id mit exact_thread_match=False.	Verwendet die Client-Standardwerte. Ausgelassener user_id wird abgelehnt. Ausgelassen agent_id und thread_id bleiben breit.	Verwendet die Speicherstandardwerte ID=None und exact_*_match=False, sodass die Dimension nicht gefiltert wird.
Expliziter Wert, einschließlich None + exact_*_match=False	Diese Dimension wird nicht gefiltert. Datensätze, deren Wert mit dem angegebenen Wert übereinstimmt, können höher eingestuft werden als andere Datensätze.	Abgelehnt für user_id, da Clientsuchen expliziten genauen Geltungsbereich von Benutzern erfordern. Für agent_id und thread_id wird diese Dimension nicht gefiltert. Datensätze, deren Wert mit dem angegebenen Wert übereinstimmt, können höher eingestuft werden als andere Datensätze.	Diese Dimension wird nicht gefiltert. Datensätze, deren Wert mit dem angegebenen Wert übereinstimmt, können höher eingestuft werden als andere Datensätze.
Explizite ID + exact_*_match=True	Entspricht dieser ID genau.	Entspricht dieser ID genau.	Entspricht dieser ID genau.
Explizite None + exact_*_match=True	Entspricht nur Datensätzen, die für diese Dimension nicht kopiert wurden.	Entspricht nur Datensätzen, die für diese Dimension nicht kopiert wurden.	Entspricht nur Datensätzen, die für diese Dimension nicht kopiert wurden.

Verwenden Sie explizites None zusammen mit exact_*_match=True, wenn nur Datensätze für diese Dimension kopiert werden sollen und die API dies zulässt. Lassen Sie das Feld aus, wenn stattdessen der Standardwert für den Vorgang verwendet werden soll.

Lebenszyklusstatusfilterung

Alle persistenten Datensätze haben einen Lebenszyklusstatus. Die Suche akzeptiert include_invalid_results in den Speicher-, Client- und Thread-APIs. Bei Client- und Thread-APIs wird standardmäßig NOT_SET_MARKER verwendet, wodurch gültige und ungültige Datensätze in die Suchergebnisse aufgenommen werden. Die Speicher-API der unteren Ebene löst den booleschen Standardwert auf dasselbe Verhalten auf. Übergeben Sie False, um Datensätze mit dem Status RecordStatus.INVALID auszulassen.

Diagrammerweiterung

Übergeben Sie num_hops von 0 bis 5 an die API für Speicher-, Client- oder Threadsuche, um verknüpften Speicherkontext an jedes direkte Speicherergebnis anzuhängen. Der Durchlauf folgt den Beziehungen in beiden Richtungen, behält die gespeicherte Beziehungsausrichtung bei und gibt einen kürzesten Pfadbaum durch die linked_results-Sequenz jedes Datensatzes zurück. Übereinstimmungen mit direkten Nachrichten, Dokumenten und Akteurprofilen bleiben in der eingestuften Ergebnismenge, werden jedoch nicht durch Diagramme erweitert. Insbesondere können durchsuchbare Bildbeschreibungen Bilddatensätze zurückgeben, ohne DOCUMENT zu einem Memory-Link-Scheitel zu machen. Geltungsbereich, Metadaten, Datensatztyp und Ablauffilter gelten für jeden verknüpften Speicher. include_invalid_results steuert weiterhin nur Suchübereinstimmungen der obersten Ebene. Es ändert nicht, welche verknüpften Speicher enthalten sind. max_linked_results begrenzt die gesamten verknüpften Speicher, die an jedes direkte Ergebnis angehängt sind, über alle Hopfen hinweg. Der Standardwert ist 100. Übergeben Sie 0, um den verknüpften Kontext zu weglassen.

Geltungsbereiche

Klasse oracleagentmemory.apis.scope.Scope

Basis: object

Stellt einen Geltungsbereich für das Einfügen oder Suchen von Informationen dar.

• Parameter:
  • Benutzer-ID str | None
  • agent_id str | None
  • thread_id str | None

user_id

Endbenutzer-ID. NOT_SET_MARKER bedeutet, dass das Feld ausgelassen wurde und durch den betriebsspezifischen Standardwert aufgelöst werden sollte. Explizites None wird beibehalten und von den Vorgangsspezifischen Regeln interpretiert. Für höhere Client-APIs wie OracleAgentMemory.search() muss der Benutzergeltungsbereich möglicherweise explizit angegeben werden. In diesen APIs kann None nur für nicht kopierte Datensätze verwendet werden.

• Typ: str | Keine

agent_id

Agent-ID. NOT_SET_MARKER bedeutet, dass das Feld ausgelassen wurde und durch den betriebsspezifischen Standardwert aufgelöst werden sollte. Explizites None wird beibehalten und von den Vorgangsspezifischen Regeln interpretiert.

• Typ: str | Keine

Thread-Kennung

Thread-ID. NOT_SET_MARKER bedeutet, dass das Feld ausgelassen wurde und durch den betriebsspezifischen Standardwert aufgelöst werden sollte. Explizites None wird beibehalten und von den Vorgangsspezifischen Regeln interpretiert.

• Typ: str | Keine

Klasse oracleagentmemory.apis.searchscope.SearchScope

Basis: Scope

Stellt den Geltungsbereich für eine Suchabfrage dar und schränkt daher ein, was zurückgegeben werden kann.

• Parameter:
  • Benutzer-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

Endbenutzer-ID. Wenn der aufgelöste exact_user_match-Wert True lautet, wird diese ID genau abgeglichen, einschließlich None. Wenn es sich um False handelt, ist die Benutzerdimension uneingeschränkt. NOT_SET_MARKER wird durch einen betriebsspezifischen Standardwert ersetzt. Für höhere Client-APIs wie OracleAgentMemory.search() muss der Benutzergeltungsbereich möglicherweise explizit angegeben werden. In diesen APIs zielt None nur auf nicht kopierte Datensätze ab, wenn exact_user_match in True aufgelöst wird.

• Typ: str | Keine

agent_id

Agent-ID. Wenn der aufgelöste exact_agent_match-Wert True lautet, wird diese ID genau abgeglichen, einschließlich None. Wenn es sich um False handelt, ist die Agent-Dimension uneingeschränkt. NOT_SET_MARKER wird je nach Vorgang, der den Geltungsbereich verwendet, durch einen Standardwert ersetzt.

• Typ: str | Keine

Thread-Kennung

Thread-ID. Wenn der aufgelöste exact_thread_match-Wert True lautet, wird diese ID genau abgeglichen, einschließlich None. Wenn es sich um False handelt, ist die Threaddimension uneingeschränkt. NOT_SET_MARKER wird je nach Vorgang, der den Geltungsbereich verwendet, durch einen Standardwert ersetzt.

• Typ: str | Keine

genaue_Benutzer_übereinstimmung

Gibt an, ob die aufgelöste user_id exakt übereinstimmen soll. True stimmt genau überein, einschließlich None. Bei False ist die Benutzerdimension uneingeschränkt. NOT_SET_MARKER wird je nach Vorgang durch einen Standardwert ersetzt. Bei höheren Client-APIs wie OracleAgentMemory.search() muss dies möglicherweise True bleiben.

• Typ: boolesch

exact_agent_match

Gibt an, ob die aufgelöste agent_id exakt übereinstimmen soll. True stimmt genau überein, einschließlich None. Mit False ist die Agent-Dimension nicht eingeschränkt. NOT_SET_MARKER wird je nach Vorgang durch einen Standardwert ersetzt.

• Typ: boolesch

genaue_Thread-Übereinstimmung

Gibt an, ob die aufgelöste thread_id exakt übereinstimmen soll. True stimmt genau überein, einschließlich None. Bei False ist die Threaddimension uneingeschränkt. NOT_SET_MARKER wird je nach Vorgang durch einen Standardwert ersetzt.

• Typ: boolesch

Suchkonfiguration

Klasse oracleagentmemory.core.MemorySearchConfig

Basen: ISearchConfig

Basiskonfiguration für Speicher-Post-Search-Verhalten.

• Parameter:
  • token_budget int | None
  • soft_token_budget int | None

Optionale Zielgröße für formatierte Suchausgabe.

Die vollständigen Ergebnisse werden nach dem ersten Ergebnis sortiert, das dieses Budget erreicht oder überschreitet. Das erste Ergebnis wird daher beibehalten, wenn kein hartes token_budget verhindert, dass es zurückgegeben wird.

Optionaler fester Grenzwert für die geschätzte Größe der formatierten Suchausgabe.

Vollständige Ergebnisse werden in Rangfolge gehalten, während ihre kumulative Schätzung dem Budget entspricht. Wenn das erste Ergebnis nicht passt, werden keine Ergebnisse zurückgegeben.

Klasse oracleagentmemory.core.TopKMemorySearchConfig

Basen: _RerankingMemorySearchConfig

Suchkonfiguration mit einem festen Maximum an direkten Ergebnissen.

• Parameter:
  • token_budget int | None
  • soft_token_budget int | None
  • Ranker IReranker | None
  • reranker_max_candidates int
  • max_results int

Maximale Anzahl direkter Ergebnisse, die vor dem erneuten Einfahren abgerufen wurden.

Klasse oracleagentmemory.core.PruningEvaluationMode

Basis: str, Enum

Steuert, wie umfangreich Suchergebnisse beim Pruning ausgewertet werden.

EXHAUSTIV = 'EXHAUSTIVE'

Bewerten Sie jedes Kandidatenergebnis einzeln. Dies bietet die umfassendste Bewertung, hat jedoch die höchste Latenz und LLM-Nutzung.

ERWEITERT = 'erweitert'

Bewerten Sie einen größeren Teil der Ergebnisse, bevor Sie entscheiden, welche zu behalten sind, und zwar auf Kosten zusätzlicher Latenz und LLM-Nutzung.

SCHNELL = 'schnell'

Priorisieren Sie eine niedrige Latenz, indem Sie die Auswertung frühzeitig stoppen, wenn sich bei weiteren Prüfungen wahrscheinlich keine Änderungen an den Ergebnissen ergeben.

Klasse oracleagentmemory.core.PruningMemorySearchConfig

Basen: _RerankingMemorySearchConfig

Suchkonfiguration, die weniger relevante direkte Ergebnisse entfernt.

Direkte Ergebnislimits werden bei jedem Such- oder Kontextkartenaufruf angegeben und vor dem erneuten Einfahren und Beschneiden angewendet.

• Parameter:
  • token_budget int | None
  • soft_token_budget int | None
  • Ranker IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • Preise ILlm

Umfangreiche Auswertung der Suchergebnisse beim Beschneiden.

Wenn keine Angabe gemacht wird, wird PruningEvaluationMode.FAST verwendet.

Anzahl der eingestuften Ergebnisregionen, die im Modus FAST oder EXTENDED ausgewertet wurden.

Dieser Parameter kann nicht festgelegt werden, wenn evaluation_mode PruningEvaluationMode.EXHAUSTIVE ist.

Bruch von hochrangigen direkten Ergebnissen vor Beschneidung geschützt.

Beispiel: Mit 0.1 werden die obersten 10 Prozent der direkten Ergebnisse geschützt.

LLM entschied, welche direkten Ergebnisse entfernt werden sollten.

Ergebnisse

Klasse oracleagentmemory.core.SearchResultFormatConfig

Basis: object

Kontrollieren Sie die portablen Suchergebnis-Renderingoptionen.

Implementierungen können eine Unterklasse mit zusätzlichen Renderingoptionen bereitstellen.

• Parameter: include_invalid_results bool – Gibt an, ob ungültige verknüpfte Datensätze ihren Inhalt enthalten. Wenn False angegeben wird, werden nur ungültige Verzweigungen ausgelassen, während ungültige Datensätze in einem Pfad zu einem gültigen Datensatz ihren Status und Linkkontext beibehalten. Lassen Sie True aus.

Klasse oracleagentmemory.core.OracleSearchResultFormatConfig

Basis: SearchResultFormatConfig

Renderingoptionen für Oracle-Suchergebnisse steuern

• Parameter:
  • show_thread_id bool: Gibt an, ob die Thread-ID des Datensatzes einbezogen werden soll. Lassen Sie False aus.
  • show_distance bool: Gibt an, ob die geschätzte Relevanz einbezogen werden soll. Lassen Sie False aus.
  • show_timestamp bool: Gibt an, ob Datensatzzeitstempel aufgenommen werden sollen. Lassen Sie True aus.
  • show_role bool – Gibt an, ob Nachrichtenrollen einbezogen werden sollen. Lassen Sie True aus.
  • show_user_id bool: Gibt an, ob Benutzer-IDs für Datensätze aufgenommen werden sollen. Lassen Sie False aus.
  • show_agent_id bool: Gibt an, ob Datensatz-Agent-IDs aufgenommen werden sollen. Lassen Sie False aus.
  • show_status bool: Gibt an, ob Lebenszyklusstatus für Datensätze berücksichtigt werden sollen. Lassen Sie True aus.
  • show_metadata bool – Gibt an, ob aufrufende Metadaten und der Grund für die Speicherinvalidierung berücksichtigt werden sollen, sofern vorhanden. Jeder Eintrag verwendet seinen Metadatenschlüssel als XML-Tag und stellt seinen Wert als Zeichenfolge dar. Lassen Sie False aus.
  • include_invalid_results bool

Klasse oracleagentmemory.core.OracleSearchResult

Basen: SearchResult

Von einem Oracle-Thread zurückgegebenes Suchergebnis.

• Parameter:
  • Abstand float: Abstand zum Abfragevektor (kleiner ist besser).
  • record Record: Ein Datensatzobjekt mit den Metadateninformationen zum persistenten Eintrag.
  • id str | None: Optionale ID, die mit dem gespeicherten Datensatz verknüpft ist.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None – Optionale grafisch verknüpfte untergeordnete Ergebnisse. Jedes Paar enthält die gespeicherte RecordRelation und das Ergebnis, das durch sie erreicht wurde.
  • format_config SearchResultFormatConfig – Standard-Renderingoptionen, die von formatted_content und von format_content() verwendet werden, wenn keine Optionen angegeben werden.

Eigenschaft content

• Rückgabetyp: str
• Beschreibung: Gibt den primären Textinhalt für den übereinstimmenden Datensatz zurück.

Methode format_content

Dieses Ergebnis und den zugehörigen Diagrammkontext als XML-sicherer Prompt-Text wiedergeben.

• Parameter: format_config SearchResultFormatConfig – Rendering-Optionen für diesen Aufruf. Weglassen, um die Standardkonfiguration dieses Ergebnisses zu verwenden. In einer bereitgestellten Konfiguration greifen ausgelassene Optionen auf die entsprechenden Optionen in dieser Standardkonfiguration zurück.
• Rückgaben: XML-sichere Ergebniswiedergabe.
• Rückgabetyp: str

Eigenschaft formatted_content

• Rückgabetyp: str

• Beschreibung: Gibt das standardmäßige XML-sichere Rendering zurück, das in Prompts verwendet wird.

• Rückgaben: XML-sicheres Rendering, das die Standardkonfiguration dieses Ergebnisses verwendet.
• Rückgabetyp: str

Eigenschaft id

• Rückgabetyp: str

  Keine

• Beschreibung: Gibt die stabile ID des abgeglichenen Datensatzes zurück, sofern verfügbar.

Eigenschaft linked_results

• Liste Rückgabetyp:[tuple[RecordRelation, SearchResult]]
• Beschreibung: Gibt verknüpfte Ergebnisse in ihrem rekursiven kürzesten Pfadbaum zurück.

Eigenschaft metadata

• Rückgabetyp: dict[str, Any]

  Keine

• Beschreibung: Gibt die Metadaten des Datensatzes zurück, sofern verfügbar.

Eigenschaft record

• Rückgabetyp: Datensatz
• Beschreibung: Gibt den zugeordneten Datensatz zurück.

Der zurückgegebene Wert kann eine einfache Record- oder ScopedRecord-Unterklasse sein. Verwenden Sie isinstance(result.record, ScopedRecord), bevor Sie öffentliche Geltungsbereichs-IDs lesen.

Eigenschaft status

• Rückgabetyp: RecordStatus

  Keine

• Beschreibung: Gibt den Lebenszyklusstatus für den zugeordneten Datensatz zurück.

Eigenschaft timestamp

• Rückgabetyp: str

  Keine

• Beschreibung: Gibt den Datensatzzeitstempel zurück, sofern verfügbar.