Usar Pesquisa Híbrida de Memória do Agente Oracle

A pesquisa semântica ajuda a encontrar informações relacionadas mesmo quando as consultas usam palavras diferentes. A pesquisa por palavra-chave ajuda a encontrar identificadores, nomes e frases exatos que a pesquisa semântica pode perder.

Este artigo explica como usar a pesquisa híbrida do Oracle Agent Memory com o Oracle Database.

A pesquisa híbrida ajuda a Memória do Agente Oracle a localizar registros por significado e texto exato. Ele combina pesquisa de texto gerenciada pela Oracle com classificação baseada em vetores, para que uma consulta possa corresponder a identificadores, como códigos de problemas, nomes de produtos e aliases, enquanto ainda se beneficia da recuperação semântica.

Neste guia, você irá:

Observação: use a pesquisa híbrida quando nem a pesquisa semântica nem a pesquisa por palavra-chave sozinhas fornecerem recuperação confiável. A pesquisa híbrida é mais útil quando os registros incluem conteúdo descritivo e termos exatos que os usuários precisam encontrar.

Dica: Para configurar o pacote, consulte Conceitos Básicos da Memória do Agente. Se você precisar de um banco de dados Oracle local para este exemplo, siga Executar o Oracle AI Database Localmente.

Configurar um Cliente do Oracle Hybrid Search

Crie um cliente Oracle Agent Memory com a pesquisa híbrida ativada. O cliente armazena registros no Oracle Database e solicita que a Oracle use um índice vetorial híbrido gerenciado para pesquisa.

Use SchemaPolicy.CREATE_IF_NECESSARY ao ativar a pesquisa híbrida pela primeira vez. Isso permite que o SDK adicione as colunas de pesquisa gerenciadas e crie o índice híbrido se elas ainda não existirem.

Use SearchStrategy.HYBRID quando quiser que o Oracle combine classificação de palavras-chave e vetores. A pesquisa híbrida requer um OracleDBEmbedder como o principal embedder do cliente para que o armazenamento e o índice vetorial híbrido gerenciado pela Oracle compartilhem o mesmo modelo no banco de dados.

Se você quiser apenas correspondência de texto, use SearchStrategy.KEYWORD. A próxima seção mostra essa configuração.

Importante: este guia requer o oracleagentmemory 26.6.0 ou mais recente. Se o seu esquema gerenciado foi criado por uma release mais antiga, inicie o aplicativo uma vez com SchemaPolicy.CREATE_IF_NECESSARY. Esses upgrades suportaram esquemas mais antigos liberados e adicionam os objetos de pesquisa exigidos pela estratégia selecionada. Essa primeira atualização pode executar reescritas de dados e DDL gerenciadas, portanto, trate-a como uma etapa de migração planejada em vez de uma inicialização normal barata. Depois que o esquema estiver pronto, você poderá voltar para SchemaPolicy.REQUIRE_EXISTING para inicialização normal.

Esquemas de desenvolvimento ou parcialmente atualizados que já reivindicam a forma da release atual não foram concluídos; em vez disso, recrie-os.

Se você usar SchemaPolicy.REQUIRE_EXISTING antes do upgrade do esquema, a criação do cliente falhará e informará quais objetos de pesquisa gerenciados estão ausentes.

Depois que um esquema for inicializado ou atualizado para pesquisa de palavra-chave ou híbrida, não o reabra com SearchStrategy.VECTOR, a menos que você recrie o esquema ou execute um backfill de incorporação. Linhas escritas por palavra-chave ou clientes híbridos podem não conter incorporações locais, portanto, a pesquisa vetorial poderia perder registros.

Aviso: A criação do índice híbrido para um esquema existente pode levar tempo. A Oracle deve verificar o texto de pesquisa armazenado existente e criar o estado do texto/vetor de índice híbrido gerenciado com base no modelo configurado no banco de dados. SchemaPolicy.CREATE_IF_NECESSARY aguarda a conclusão desse DDL antes do retorno da inicialização do cliente; portanto, execute o primeiro upgrade híbrido como uma migração planejada ou operação de manutenção para esquemas grandes.

Observação: Quando o SDK cria um índice de vetor híbrido gerenciado, ele também cria uma preferência de vetorizador DBMS_VECTOR_CHAIN nomeada pelo esquema gerenciado. A preferência armazena a configuração do vetorizador no modelo OracleDBEmbedder configurado e espera-se que sejam metadados leves. O nome da preferência gerada é determinístico para o esquema gerenciado e segue o prefixo de nome de tabela configurado quando ele se encaixa no limite de nome de preferência do Oracle Text. Você pode inspecionar preferências com as exibições do Oracle Text, como CTX_USER_PREFERENCES e CTX_USER_PREFERENCE_VALUES.

Observação: Este exemplo usa OracleDBEmbedder. A Oracle usa o modelo no banco de dados desse incorporador ao criar o índice híbrido, de modo que o principal incorporador e o índice híbrido compartilhem um modelo de banco de dados.

O exemplo também usa SearchIndexSyncMode.ON_COMMIT. Isso mantém o índice híbrido atualizado após cada gravação confirmada, para que as memórias recém-adicionadas possam ser pesquisadas imediatamente. Use SearchIndexSyncMode.MANUAL quando você planeja executar a sincronização de índice de pesquisa sozinho ou SearchIndexSyncMode.AUTO quando quiser que a Oracle atualize o índice híbrido em segundo plano e possa tolerar resultados de pesquisa atrasados em relação às gravações recentes. Esta configuração se aplica à manutenção contínua após a existência do índice de pesquisa inicial; ela não torna a primeira criação de índice assíncrona.

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
    SearchIndexSyncMode,
    SearchStrategy,
)
from oracleagentmemory.core.embedders import OracleDBEmbedder


db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)

db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="YOUR_DB_EMBEDDING_MODEL",
    embedding_dimension=384,
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)
Referência de API: OracleAgentMemory Português do Brasil Política de Esquema PesquisarEstratégia SearchIndexSyncMode

Usar somente pesquisa de palavra-chave

Use SearchStrategy.KEYWORD quando quiser que a pesquisa corresponda a palavras armazenadas, identificadores, aliases, nomes de produtos ou frases curtas, e não quiser a classificação vetorial. A pesquisa por palavra-chave lê o mesmo texto de pesquisa armazenado usado pela pesquisa híbrida, mas não usa fusão vetorial.

A pesquisa por palavra-chave não precisa de um incorporador Python. Se o SDK precisar criar objetos de pesquisa para um novo esquema de palavra-chave, ele criará um índice do Oracle Text sobre o texto de pesquisa armazenado. A atualização do índice de texto da palavra-chave de controle SearchIndexSyncMode.ON_COMMIT e SearchIndexSyncMode.MANUAL.

keyword_memory = OracleAgentMemory(
    connection=db_pool,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.KEYWORD,
)

As mesmas chamadas add_memory() e search() mostradas abaixo funcionam com SearchStrategy.KEYWORD. A diferença é a classificação: a pesquisa por palavra-chave retorna registros com base apenas na correspondência de texto, enquanto a pesquisa híbrida combina correspondência de texto com classificação de vetor.

Referência de API: OracleAgentMemory PesquisarEstratégia

Usar estratégias de pesquisa compatíveis

A primeira vez que o SDK cria ou faz upgrade do esquema gerenciado, ele registra como os dados de recuperação armazenados são preparados para pesquisa. O modo registrado é verificado toda vez que um cliente de banco de dados é iniciado. Isso evita que um cliente use uma estratégia que possa perder registros silenciosamente.

Se a estratégia solicitada for compatível com o esquema, mas não corresponder ao modo registrado, o SDK emitirá uma advertência. O cliente ainda pode começar, mas o aviso ajuda a perceber a diferença e confirmar que é intencional.

Aviso: A primeira criação do índice híbrido em relação aos dados existentes pode ser de longa execução porque a Oracle cria o estado de índice híbrido gerenciado com base no texto de pesquisa armazenado. SearchIndexSyncMode controla a manutenção contínua do índice após a existência do índice; ele não torna a primeira criação assíncrona.

Use SchemaPolicy.CREATE_IF_NECESSARY quando você mover intencionalmente um esquema de vetor para palavra-chave ou híbrido, ou de palavra-chave para híbrido. Use SchemaPolicy.REQUIRE_EXISTING depois que o esquema estiver pronto e você quiser que a inicialização valide o esquema sem alterar objetos de banco de dados.

Referência de API: SchemaPolicy PesquisarEstratégia

Armazenar uma memória pesquisável

Comece com uma memória normal. Com a API OracleAgentMemory.add_memory(), o sistema Oracle usa o próprio conteúdo da memória como texto pesquisável. Este é o caminho mais simples e geralmente é suficiente quando os usuários procuram palavras ou frases que já aparecem na memória.

user_id = "user_123"

memory.add_memory(
    "The user calls the Milan outage the renewal blocker.",
    user_id=user_id,
)

Referência de API: OracleAgentMemory

Usuários de Identificadores de Loja Podem Procurar

Quando os usuários podem pesquisar por um código de emissão exato, número da fatura, nome do produto ou alias, inclua esse texto na memória que você armazena. A pesquisa híbrida pode então corresponder ao texto exato e ainda usar a classificação vetorial para consultas em linguagem natural.

Mantenha a memória legível. Uma frase curta que inclui o identificador importante é muitas vezes suficiente. Neste exemplo, as memórias incluem identificadores de problemas e solicitações que os usuários provavelmente digitarão posteriormente.

memory.add_memory(
    "The follow-up fix for the Milan outage is the edge-cluster retry patch, "
    "tracked as ORA-27102.",
    user_id=user_id,
)

memory.add_memory(
    "The renewal request INV-48291 stays attached to the Milan blocker ORA-27102.",
    user_id=user_id,
)

Referência de API: OracleAgentMemory

Pesquisar por Identificador ou Frase

Use a API search() normal. A pesquisa híbrida é executada por trás da mesma interface de pesquisa do Oracle Agent Memory, para que você possa continuar usando escopos, limites de resultados e filtros de tipo de registro, como de costume.

A primeira consulta procura um código de problema exato armazenado no texto da memória. A segunda consulta procura uma frase em linguagem natural do mesmo conjunto de memórias.

for query in ["ORA-27102", "renewal blocker"]:
    print(f"\nSearch results for {query!r}:")
    results = memory.search(
        query=query,
        user_id=user_id,
        max_results=5,
        record_types=["memory"],
    )
    print_search_results(results)

Observação: A ordem dos resultados da pesquisa pode variar de acordo com seus dados armazenados, configuração de índice híbrido e comportamento de pontuação da Oracle. Em testes ou demonstrações, verifique se os registros esperados são retornados em vez de depender de uma classificação exata.

Referência de API: OracleAgentMemory Resultado do OracleSearch

Conclusão

Neste guia, você ativou a pesquisa híbrida gerenciada pela Oracle, viu quando usar a pesquisa somente por palavra-chave, armazenou uma memória regular, incluiu identificadores pesquisáveis no texto da memória e consultou memórias por identificador exato e frase em linguagem natural.

Depois de aprender a ativar a pesquisa híbrida no Oracle DB, agora você poderá prosseguir para Armazenamentos e Esquema.

Código Inteiro

#Copyright © 2026 Oracle and/or its affiliates.
#This software is under the Apache License 2.0
#(LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
#(UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

#Oracle Agent Memory Code Example - Oracle Hybrid Search
#-------------------------------------------------------

##Configure an Oracle hybrid search client

import oracledb

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    OracleAgentMemory,
    SchemaPolicy,
    SearchIndexSyncMode,
    SearchStrategy,
)
from oracleagentmemory.core.embedders import OracleDBEmbedder


db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)

db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="YOUR_DB_EMBEDDING_MODEL",
    embedding_dimension=384,
)

memory = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)



##Configure an Oracle keyword search client

keyword_memory = OracleAgentMemory(
    connection=db_pool,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.KEYWORD,
)


def print_search_results(results: list) -> None:
    for result in results:
        print(f"- [{result.record.record_type}] {result.content}")



##Store a basic hybrid search memory

user_id = "user_123"

memory.add_memory(
    "The user calls the Milan outage the renewal blocker.",
    user_id=user_id,
)



##Store identifiers users may search for

memory.add_memory(
    "The follow-up fix for the Milan outage is the edge-cluster retry patch, "
    "tracked as ORA-27102.",
    user_id=user_id,
)

memory.add_memory(
    "The renewal request INV-48291 stays attached to the Milan blocker ORA-27102.",
    user_id=user_id,
)



##Search hybrid records by identifier or phrase

for query in ["ORA-27102", "renewal blocker"]:
    print(f"\nSearch results for {query!r}:")
    results = memory.search(
        query=query,
        user_id=user_id,
        max_results=5,
        record_types=["memory"],
    )
    print_search_results(results)