Oracle Agent 메모리 하이브리드 검색 사용

의미 검색은 질의가 다른 단어를 사용하는 경우에도 관련 정보를 찾는 데 도움이 됩니다. 키워드 검색은 의미 검색에서 놓칠 수 있는 정확한 식별자, 이름 및 구문을 찾는 데 도움이 됩니다.

이 문서에서는 Oracle Database에서 Oracle 에이전트 메모리 하이브리드 검색을 사용하는 방법에 대해 설명합니다.

하이브리드 검색을 통해 Oracle 에이전트 메모리는 의미와 정확한 텍스트로 레코드를 찾을 수 있습니다. Oracle이 관리하는 텍스트 검색과 벡터 기반 순위를 결합하므로 쿼리는 문제 코드, 제품 이름 및 별칭과 같은 식별자와 일치하면서도 의미 검색의 이점을 얻을 수 있습니다.

이 설명서에서는 다음 작업을 수행합니다.

주: 의미 검색이나 키워드 검색만으로도 신뢰할 수 있는 검색을 제공하지 않는 경우 하이브리드 검색을 사용하십시오. 하이브리드 검색은 레코드에 설명 콘텐츠와 사용자가 찾아야 하는 정확한 용어가 모두 포함된 경우 가장 유용합니다.

힌트: 패키지 설정은 에이전트 메모리 시작하기를 참조하십시오. 이 예에 대한 로컬 Oracle 데이터베이스가 필요한 경우 Run Oracle AI Database Locally를 따르십시오.

Oracle 하이브리드 검색 클라이언트 구성

하이브리드 검색이 사용으로 설정된 Oracle 에이전트 메모리 클라이언트를 생성합니다. 클라이언트는 Oracle Database에 레코드를 저장하고 Oracle에 검색에 관리형 하이브리드 벡터 인덱스를 사용하도록 요청합니다.

하이브리드 검색을 처음 사용으로 설정하는 경우 SchemaPolicy.CREATE_IF_NECESSARY를 사용합니다. 이렇게 하면 SDK가 관리 검색 열을 추가하고 하이브리드 인덱스가 없는 경우 생성할 수 있습니다.

Oracle이 키워드와 벡터 순위를 결합하도록 하려면 SearchStrategy.HYBRID를 사용합니다. 하이브리드 검색에는 클라이언트의 기본 embedder로 OracleDBEmbedder가 필요하므로 저장소와 Oracle 관리 하이브리드 벡터 인덱스는 동일한 데이터베이스 내 모델을 공유합니다.

텍스트 일치만 원할 경우 대신 SearchStrategy.KEYWORD를 사용하십시오. 다음 섹션에서는 해당 설정을 보여 줍니다.

중요: 이 설명서에는 oracleagentmemory 26.6.0 이상이 필요합니다. 관리 스키마가 이전 릴리스에 의해 생성된 경우 SchemaPolicy.CREATE_IF_NECESSARY를 사용하여 응용 프로그램을 한 번 시작합니다. 이 업그레이드는 기존 릴리스된 스키마를 제자리에 지원하고 선택된 전략에 필요한 검색 객체를 추가합니다. 이 첫 번째 업그레이드는 관리형 DDL 및 데이터 재작성을 수행할 수 있으므로 정상적인 시작이 아닌 계획된 이전 단계로 처리하십시오. 스키마가 준비되면 정상적인 시작을 위해 SchemaPolicy.REQUIRE_EXISTING로 다시 전환할 수 있습니다.

현재 릴리스 구성을 이미 주장하는 개발 또는 부분적으로 업데이트된 스키마가 현재 위치에서 완료되지 않았습니다. 대신 다시 생성하십시오.

스키마를 업그레이드하기 전에 SchemaPolicy.REQUIRE_EXISTING를 사용하는 경우 클라이언트 생성이 실패하고 어떤 관리 검색 객체가 누락되었는지 알려줍니다.

키워드 또는 하이브리드 검색에 대해 스키마가 초기화되거나 업그레이드된 후에는 스키마를 다시 생성하거나 포함 백필을 실행하지 않는 한 SearchStrategy.VECTOR를 사용하여 스키마를 다시 열지 마십시오. 키워드 또는 하이브리드 클라이언트로 작성된 행에는 로컬 임베딩이 포함되지 않을 수 있으므로 벡터 검색에서 레코드를 놓칠 수 있습니다.

경고: 기존 스키마에 대한 하이브리드 인덱스를 생성하는 데 시간이 걸릴 수 있습니다. Oracle은 기존의 저장된 검색 텍스트를 스캔하고 구성된 데이터베이스 내 모델에서 관리되는 하이브리드 인덱스 텍스트/벡터 상태를 구축해야 합니다. SchemaPolicy.CREATE_IF_NECESSARY는 클라이언트 시작이 반환되기 전에 해당 DDL이 완료될 때까지 기다리므로 대규모 스키마에 대해 계획된 이전 또는 유지 관리 작업으로 첫번째 하이브리드 업그레이드를 실행합니다.

주: SDK가 관리되는 하이브리드 벡터 인덱스를 생성하면 관리되는 스키마에 의해 이름이 지정된 DBMS_VECTOR_CHAIN 벡터화기 환경설정도 생성됩니다. 기본 설정은 구성된 OracleDBEmbedder 모델의 벡터화기 구성을 저장하며 경량 메타데이터가 될 것으로 예상됩니다. 생성된 기본 설정 이름은 관리 스키마에 대해 결정적이며 Oracle Text의 기본 설정 이름 제한에 맞게 구성된 테이블 이름 접두어를 따릅니다. CTX_USER_PREFERENCES 및 CTX_USER_PREFERENCE_VALUES와 같은 Oracle Text 뷰를 사용하여 환경설정을 검사할 수 있습니다.

주: 이 예에서는 OracleDBEmbedder를 사용합니다. Oracle은 하이브리드 인덱스를 생성할 때 이 임베더의 데이터베이스 내 모델을 사용하므로 기본 임베더와 하이브리드 인덱스는 하나의 DB 모델을 공유합니다.

이 예에서는 SearchIndexSyncMode.ON_COMMIT도 사용합니다. 이렇게 하면 각 커밋된 쓰기 후에 하이브리드 인덱스가 최신 상태로 유지되므로 새로 추가된 메모리를 즉시 검색할 수 있습니다. 검색 인덱스 동기화를 직접 실행하려는 경우 SearchIndexSyncMode.MANUAL를 사용하고, Oracle이 백그라운드에서 하이브리드 인덱스를 새로 고치고 최근 쓰기보다 지연되는 검색 결과를 허용하려는 경우 SearchIndexSyncMode.AUTO를 사용합니다. 이 설정은 초기 검색 인덱스가 존재한 후 진행 중인 유지 관리에 적용되며 첫번째 인덱스가 비동기적으로 생성되지 않습니다.

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,
)
API 참조: OracleAgentMemory OracleDBEmbedder 스키마 정책 전략 검색 검색 인덱스 동기화 모드

키워드 검색만 사용

저장된 단어, 식별자, 별칭, 제품 이름 또는 짧은 구문과 일치하고 벡터 순위를 지정하지 않으려는 경우 SearchStrategy.KEYWORD를 사용합니다. 키워드 검색은 하이브리드 검색에서 사용하는 것과 동일한 저장된 검색 텍스트를 읽지만 벡터 융합은 사용하지 않습니다.

키워드 검색에는 Python 임베더가 필요하지 않습니다. SDK가 새 키워드 스키마에 대한 검색 객체를 생성해야 하는 경우 저장된 검색 텍스트에 대해 Oracle Text 인덱스를 생성합니다. SearchIndexSyncMode.ON_COMMIT 및 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,
)

아래 표시된 동일한 add_memory() 및 search() 호출은 SearchStrategy.KEYWORD에서 작동합니다. 차이점은 순위입니다. 키워드 검색은 텍스트 일치를 기반으로만 레코드를 반환하고, 하이브리드 검색은 텍스트 일치와 벡터 순위를 결합합니다.

API 참조: OracleAgentMemory 전략 검색

호환 검색 전략 사용

SDK는 관리 스키마를 처음 생성하거나 업그레이드할 때 저장된 검색 데이터가 검색을 위해 준비되는 방식을 기록합니다. 기록된 모드는 DB 클라이언트가 시작될 때마다 검사됩니다. 이렇게 하면 클라이언트가 레코드를 자동으로 놓칠 수 있는 전략을 사용할 수 없습니다.

요청된 전략이 스키마와 호환되지만 기록된 모드와 일치하지 않으면 SDK에서 경고가 발생합니다. 클라이언트는 계속 시작할 수 있지만 경고를 통해 차이를 확인하고 의도적인지 확인할 수 있습니다.

경고: Oracle은 저장된 검색 텍스트에서 관리되는 하이브리드 인덱스 상태를 구축하기 때문에 기존 데이터에 대한 하이브리드 인덱스를 처음 생성하는 작업은 오래 실행될 수 있습니다. SearchIndexSyncMode는 인덱스가 존재하는 후 진행 중인 인덱스 유지 관리를 제어하며 첫번째 빌드를 비동기적으로 만들지 않습니다.

의도적으로 벡터에서 키워드 또는 하이브리드로 스키마를 이동하거나 키워드에서 하이브리드로 스키마를 이동하는 경우 SchemaPolicy.CREATE_IF_NECESSARY를 사용합니다. 스키마가 준비된 후 SchemaPolicy.REQUIRE_EXISTING를 사용하여 데이터베이스 객체를 변경하지 않고 스키마를 검증하려고 합니다.

API 참조: SchemaPolicy 전략 검색

검색 가능한 메모리 저장

정상적인 기억으로 시작하십시오. OracleAgentMemory.add_memory() API에서 Oracle은 메모리 콘텐츠 자체를 검색 가능한 텍스트로 사용합니다. 이것은 가장 간단한 경로이며 일반적으로 사용자가 메모리에 이미 나타나는 단어 또는 구를 검색할 때 충분합니다.

user_id = "user_123"

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

API 참조: OracleAgentMemory

사용자가 검색할 수 있는 점포 식별자

사용자가 정확한 문제 코드, 송장 번호, 제품 이름 또는 별칭으로 검색할 수 있는 경우 저장한 메모리에 해당 텍스트를 포함합니다. 그런 다음 하이브리드 검색은 정확한 텍스트와 일치할 수 있으며 자연어 쿼리에 벡터 순위를 사용할 수 있습니다.

메모리를 읽을 수 있도록 유지합니다. 중요한 식별자를 포함하는 짧은 문장으로도 충분합니다. 이 예에서는 메모리에 사용자가 나중에 입력할 수 있는 문제 및 요청 식별자가 포함됩니다.

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,
)

API 참조: OracleAgentMemory

식별자 또는 구문으로 검색

일반 search() API를 사용합니다. 하이브리드 검색은 동일한 Oracle Agent 메모리 검색 인터페이스에서 실행되므로 범위, 결과 제한 및 레코드 유형 필터를 계속 사용할 수 있습니다.

첫번째 query는 메모리 텍스트에 저장된 정확한 문제 코드를 검색합니다. 두번째 질의는 동일한 메모리 집합에서 자연어 구문을 검색합니다.

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)

주: 검색 결과 순서는 저장된 데이터, 하이브리드 인덱스 구성 및 Oracle 점수부여 동작에 따라 다를 수 있습니다. 테스트 또는 데모에서는 정확한 순위에 의존하지 않고 예상 레코드가 반환되는지 확인합니다.

API 참조: OracleAgentMemory 오라클 검색 결과

결론

이 설명서에서는 Oracle 관리 하이브리드 검색을 사용으로 설정하고, 키워드 전용 검색을 사용해야 하는 경우를 확인하고, 일반 메모리를 저장하고, 메모리 텍스트에 검색 가능한 식별자를 포함하고, 정확한 식별자 및 자연어 구문으로 메모리를 질의했습니다.

Oracle DB에서 하이브리드 검색을 사용으로 설정하는 방법을 학습한 후 이제 저장소 및 스키마로 이동할 수 있습니다.

전체 코드

#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)