검색

이 페이지에서는 개발자 관련 범위 지정 도우미와 구체적인 Oracle 검색 결과 유형을 함께 제공합니다.

범위 해상도

각 범위 필드에 대해 다음 세 가지 작업 중 하나를 수행할 수 있습니다.

• 해당 API 계층의 기본값을 사용하려면 생략합니다. Python 서명 및 SearchScope에서 이 생략된 상태는 NOT_SET_MARKER로 표시됩니다.
• 해당 값을 사용하기 위한 구체적인 ID를 지정합니다.
• 해당 차원에서 레코드의 범위가 지정되지 않았음을 나타내려면 None를 지정합니다. 예를 들어, agent_id=None는 레코드가 하나의 에이전트에 연결되지 않음을 의미합니다.

각 저장된 레코드에는 user_id, agent_id 및 thread_id의 세 가지 독립 범위 필드가 있습니다. 각 필드에는 구체적 ID 또는 None가 포함될 수 있습니다.

예제는 다음과 같습니다.

• thread_id=None는 레코드가 한 스레드에 연결되지 않았음을 의미합니다.
• agent_id=None는 레코드가 한 에이전트에 연결되지 않았음을 의미합니다.
• user_id="u1", agent_id=None, thread_id=None는 레코드의 범위가 사용자 u1로 지정되지만 특정 에이전트나 스레드에는 지정되지 않음을 의미합니다.

동일한 범위 지정 규칙이 동기 및 비동기 검색 API 모두에 적용됩니다.

아래 테이블에서 ID는 해당하는 정확한 일치 플래그와 함께 user_id, agent_id 또는 thread_id를 의미합니다.

API 계층별 검색 범위 분석

사례	thread.search()	OracleAgentMemory.search()	store.search()
ID 생략됨	스레드 기본값(정확한 user_id 및 agent_id)과 현재 thread_id(exact_thread_match=False 포함)을 사용합니다.	클라이언트 기본값을 사용합니다. 생략된 user_id가 거부되었습니다. agent_id 및 thread_id를 생략했습니다.	차원이 필터링되지 않도록 저장소 기본값 ID=None 및 exact_*_match=False을 사용합니다.
None + exact_*_match=False를 포함한 명시적 값	해당 차원은 필터링되지 않습니다. 값이 지정된 레코드와 일치하는 레코드는 다른 레코드보다 높은 등급을 지정할 수 있습니다.	user_id의 경우 클라이언트 검색에 명시적인 정확한 사용자 범위 지정이 필요하므로 거부됩니다. agent_id 및 thread_id의 경우 해당 차원이 필터링되지 않습니다. 값이 지정된 레코드와 일치하는 레코드는 다른 레코드보다 높은 등급을 지정할 수 있습니다.	해당 차원은 필터링되지 않습니다. 값이 지정된 레코드와 일치하는 레코드는 다른 레코드보다 높은 등급을 지정할 수 있습니다.
명시적 ID + exact_*_match=True	이 ID와 정확히 일치합니다.	이 ID와 정확히 일치합니다.	이 ID와 정확히 일치합니다.
명시적 None + exact_*_match=True	해당 차원에서 범위가 지정되지 않은 레코드만 일치시킵니다.	해당 차원에서 범위가 지정되지 않은 레코드만 일치시킵니다.	해당 차원에서 범위가 지정되지 않은 레코드만 일치시킵니다.

해당 차원에서 범위가 지정되지 않은 레코드만 원하고 API에서 허용하는 경우 명시적 None를 exact_*_match=True와 함께 사용합니다. 대신 공정 기본값을 원하는 경우 필드를 생략합니다.

수명 주기 상태 필터링

모든 지속 레코드는 수명 주기 상태를 가집니다. 검색은 저장소, 클라이언트 및 스레드 API에서 include_invalid_results를 허용합니다. 클라이언트 및 스레드 API의 기본값은 NOT_SET_MARKER이며, 검색 결과에 적합하고 부적합한 레코드를 포함하도록 분석됩니다. 하위 레벨 저장소 API는 부울 기본값을 동일한 동작으로 해결합니다. False을 전달하여 상태가 RecordStatus.INVALID인 레코드를 생략합니다.

그래프 확장

0에서 5까지 num_hops를 저장소, 클라이언트 또는 스레드 검색 API에 전달하여 연결된 메모리 컨텍스트를 각 직접 메모리 결과에 연결합니다. 순회는 두 방향 중 하나의 관계를 따르고 저장된 관계 방향을 보존하며 각 레코드의 linked_results 시퀀스를 통해 가장 짧은 경로 트리를 반환합니다. 직접 메시지, 문서 및 수행자 프로파일 일치 항목은 순위가 지정된 결과 집합에 남아 있지만 그래프로 확장되지는 않습니다. 특히 검색 가능한 이미지 설명은 DOCUMENT를 메모리 링크 정점으로 만들지 않고도 이미지 레코드를 반환할 수 있습니다. 범위, 메타데이터, 레코드 유형 및 만료 필터는 연결된 모든 메모리에 적용됩니다. include_invalid_results는 계속해서 최상위 레벨 검색 일치 항목만 제어합니다. 연결된 메모리는 변경되지 않습니다. max_linked_results는 모든 홉에서 각 직접 결과에 연결된 총 연결된 메모리를 제한합니다. 기본값은 100입니다. 링크된 컨텍스트를 생략하려면 0를 전달합니다.

범위

클래스 oracleagentmemory.apis.scope.Scope

기준: object

정보 삽입 또는 검색에 대한 범위를 나타냅니다.

• 매개변수:
  • user_id str | None
  • agent_id str | None
  • thread_id str | None

user_id

고객 ID입니다. NOT_SET_MARKER는 필드가 생략되었으며 작업별 기본값으로 해결되어야 함을 의미합니다. 명시적 None는 작업별 규칙에 따라 보존되고 해석됩니다. OracleAgentMemory.search()와 같은 상위 레벨의 클라이언트 API는 사용자 범위를 명시적으로 요구할 수 있습니다. 해당 API에서 None는 범위가 지정되지 않은 레코드만 대상으로 지정할 수 있습니다.

• 유형: str | None

에이전트 ID

에이전트 ID. NOT_SET_MARKER는 필드가 생략되었으며 작업별 기본값으로 해결되어야 함을 의미합니다. 명시적 None는 작업별 규칙에 따라 보존되고 해석됩니다.

• 유형: str | None

thread_id

스레드 ID. NOT_SET_MARKER는 필드가 생략되었으며 작업별 기본값으로 해결되어야 함을 의미합니다. 명시적 None는 작업별 규칙에 따라 보존되고 해석됩니다.

• 유형: str | None

클래스 oracleagentmemory.apis.searchscope.SearchScope

기준: Scope

검색 질의의 범위를 나타내므로 반환할 수 있는 항목을 제한합니다.

• 매개변수:
  • 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입니다. 해결된 exact_user_match 값이 True인 경우 이 ID는 None를 포함하여 정확히 일치됩니다. False인 경우 사용자 차원이 제한되지 않습니다. NOT_SET_MARKER는 작업별 기본값으로 바뀝니다. OracleAgentMemory.search()와 같은 상위 레벨의 클라이언트 API는 사용자 범위를 명시적으로 요구할 수 있습니다. 해당 API에서 None는 exact_user_match가 True로 확인될 때 범위가 지정되지 않은 레코드만 대상으로 지정합니다.

• 유형: str | None

에이전트 ID

에이전트 ID. 해결된 exact_agent_match 값이 True인 경우 이 ID는 None를 포함하여 정확히 일치됩니다. False인 경우 에이전트 차원이 제한되지 않습니다. NOT_SET_MARKER는 범위를 사용하는 작업에 따라 기본값으로 바뀝니다.

• 유형: str | None

thread_id

스레드 ID. 해결된 exact_thread_match 값이 True인 경우 이 ID는 None를 포함하여 정확히 일치됩니다. False인 경우 스레드 차원이 제한되지 않습니다. NOT_SET_MARKER는 범위를 사용하는 작업에 따라 기본값으로 바뀝니다.

• 유형: str | None

정확한_사용자_일치

해결된 user_id와 정확히 일치할지 여부입니다. True는 None를 포함하여 정확히 일치합니다. False는 사용자 차원을 제약 없는 상태로 유지합니다. NOT_SET_MARKER는 작업에 따라 기본값으로 바뀝니다. OracleAgentMemory.search()와 같은 상위 레벨 클라이언트 API의 경우 이를 True로 유지해야 할 수 있습니다.

• 유형: bool

정확한_에이전트_일치

해결된 agent_id와 정확히 일치할지 여부입니다. True는 None를 포함하여 정확히 일치합니다. False는 에이전트 차원을 제약 없는 상태로 유지합니다. NOT_SET_MARKER는 작업에 따라 기본값으로 바뀝니다.

• 유형: bool

정확한_스레드_일치

해결된 thread_id와 정확히 일치할지 여부입니다. True는 None를 포함하여 정확히 일치합니다. False는 스레드 차원을 제약 없는 상태로 유지합니다. NOT_SET_MARKER는 작업에 따라 기본값으로 바뀝니다.

• 유형: bool

검색 구성

클래스 oracleagentmemory.core.MemorySearchConfig

기준: ISearchConfig

메모리 사후 검색 동작에 대한 기본 구성입니다.

• 매개변수:
  • token_budget int | None
  • soft_token_budget int | None

형식이 지정된 검색 출력에 대한 선택적 대상 크기입니다.

전체 결과는 이 예산에 도달하거나 초과하는 첫 번째 결과를 통해 순위에 따라 유지됩니다. 따라서 첫 번째 결과는 하드 token_budget가 반환되지 않도록 방지할 때 유지됩니다.

형식이 지정된 검색 출력의 예상 크기에 대한 선택적 하드 한계입니다.

전체 결과는 순위에 따라 유지되며 누적 예측은 예산에 맞습니다. 첫 번째 결과가 맞지 않으면 결과가 반환되지 않습니다.

클래스 oracleagentmemory.core.TopKMemorySearchConfig

기준: _RerankingMemorySearchConfig

최대 직접 결과가 고정된 검색 구성입니다.

• 매개변수:
  • token_budget int | None
  • soft_token_budget int | None
  • 리랭커 IReranker | None
  • reranker_max_candidates int
  • max_results int

등급을 재지정하기 전에 검색된 최대 직접 결과 수입니다.

클래스 oracleagentmemory.core.PruningEvaluationMode

기준: str, Enum

제거 중 광범위한 검색 결과를 평가하는 방법을 제어합니다.

배상 = 'EXHAUSTIVE'

모든 후보자 결과를 개별적으로 평가합니다. 이는 가장 완벽한 평가를 제공하지만, 대기 시간과 LLM 사용량이 가장 높습니다.

확장됨 = 'EXTENDED'

추가 대기 시간 및 LLM 사용 비용으로 유지할 결과를 결정하기 전에 결과의 더 넓은 부분을 평가합니다.

빠른 속도 = 'FAST'

추가 검사가 보존되는 결과를 변경하지 않을 가능성이 있는 경우 조기에 평가를 중지하여 대기 시간이 짧은 우선순위를 지정합니다.

클래스 oracleagentmemory.core.PruningMemorySearchConfig

기준: _RerankingMemorySearchConfig

관련성이 낮은 직접 결과를 제거하는 검색 구성입니다.

직접 결과 제한은 각 검색 또는 컨텍스트 카드 호출에 제공되며 순위 재지정 및 제거 전에 적용됩니다.

• 매개변수:
  • token_budget int | None
  • soft_token_budget int | None
  • 리랭커 IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • pruner ILlm

제거 중 검색 결과를 광범위하게 평가하는 방법

생략할 경우 PruningEvaluationMode.FAST가 사용됩니다.

FAST 또는 EXTENDED 모드에서 평가된 순위 결과 영역 수입니다.

evaluation_mode가 PruningEvaluationMode.EXHAUSTIVE인 경우 이 매개변수를 설정할 수 없습니다.

제거로부터 보호되는 최고 등급의 직접 결과의 일부입니다.

예를 들어, 0.1는 직접 결과의 상위 10%를 보호합니다.

LLM은 제거할 직접 결과를 결정하는 데 사용됩니다.

결과

클래스 oracleagentmemory.core.SearchResultFormatConfig

기준: object

이식 가능한 검색 결과 렌더링 옵션을 제어합니다.

구현은 하위 클래스에 추가 렌더링 옵션을 제공할 수 있습니다.

• 매개변수: include_invalid_results bool – 부적합한 링크된 레코드에 해당 콘텐츠가 포함되는지 여부입니다. False인 경우 부적합한 전용 분기가 생략되고, 적합한 레코드 경로의 부적합한 레코드는 해당 상태 및 링크 컨텍스트를 유지합니다. True를 사용하려면 생략합니다.

클래스 oracleagentmemory.core.OracleSearchResultFormatConfig

기준: SearchResultFormatConfig

Oracle 검색 결과 렌더링 옵션을 제어합니다.

• 매개변수:
  • show_thread_id bool – 레코드의 스레드 식별자를 포함할지 여부입니다. False를 사용하려면 생략합니다.
  • show_distance bool – 예상 관련성을 포함할지 여부입니다. False를 사용하려면 생략합니다.
  • show_timestamp bool – 레코드 시간 기록을 포함할지 여부입니다. True를 사용하려면 생략합니다.
  • show_role bool – 메시지 역할을 포함할지 여부입니다. True를 사용하려면 생략합니다.
  • show_user_id bool – 레코드 사용자 식별자를 포함할지 여부입니다. False를 사용하려면 생략합니다.
  • show_agent_id bool – 레코드 에이전트 식별자를 포함할지 여부입니다. False를 사용하려면 생략합니다.
  • show_status bool – 레코드 수명 주기 상태를 포함할지 여부입니다. True를 사용하려면 생략합니다.
  • show_metadata bool – 호출자 메타데이터 및 메모리 무효화 이유(있을 때)를 포함할지 여부입니다. 각 항목은 메타 데이터 키를 XML 태그로 사용하고 해당 값을 문자열로 렌더링합니다. False를 사용하려면 생략합니다.
  • include_invalid_results bool

클래스 oracleagentmemory.core.OracleSearchResult

기준: SearchResult

Oracle 스레드에서 반환된 검색 결과입니다.

• 매개변수:
  • distance float – 쿼리 벡터로부터의 거리입니다(더 작을수록 좋습니다).
  • record Record – 지속 항목에 대한 메타 데이터 정보를 포함하는 레코드 객체입니다.
  • id str | None – 저장된 레코드와 연관된 선택적 식별자입니다.
  • linked_results list tuple[[RecordRelation, SearchResult]] | None – 그래프에 연결된 선택적 하위 결과입니다. 각 쌍은 저장된 RecordRelation을 포함하고 그 결과를 통해 도달했습니다.
  • format_config SearchResultFormatConfig – 제공된 옵션이 없을 때 formatted_content 및 format_content()에서 사용되는 기본 렌더링 옵션입니다.

등록 정보 content

• 반품 유형: str
• 설명: 일치된 레코드에 대한 기본 텍스트 콘텐츠를 반환합니다.

방법 format_content

이 결과와 해당 그래프 컨텍스트를 XML에 안전한 프롬프트 텍스트로 렌더링합니다.

• 매개변수: format_config SearchResultFormatConfig – 이 호출에 대한 렌더링 옵션입니다. 이 결과의 기본 구성을 사용하려면 생략하십시오. 제공된 구성에서 생략된 옵션은 해당 기본 구성의 해당 옵션으로 폴백됩니다.
• 반환: XML에 안전한 결과 렌더링입니다.
• 반환 유형: str

등록 정보 formatted_content

• 반품 유형: str

• 설명: 프롬프트에 사용되는 기본 XML 안전 렌더링을 반환합니다.

• 반환: 이 결과의 기본 구성을 사용하는 XML에 안전한 렌더링입니다.
• 반환 유형: str

재산 id

• 반품 유형: str

  없음

• 설명: 일치된 레코드의 안정적인 식별자를 반환합니다(사용 가능한 경우).

등록 정보 linked_results

• 반환 유형: 목록[튜플[RecordRelation, SearchResult]]
• 설명: 연결된 결과를 순환 최단 경로 트리에 반환합니다.

등록 정보 metadata

• 반품 유형: dict[str, Any]

  없음

• 설명: 레코드 메타데이터(사용 가능한 경우)를 반환합니다.

등록 정보 record

• 반품 유형: 레코드
• 설명: 일치된 레코드를 반환합니다.

반환된 값은 일반 Record 또는 ScopedRecord 하위 클래스일 수 있습니다. 퍼블릭 범위 식별자를 읽기 전에 isinstance(result.record, ScopedRecord)를 사용하십시오.

등록 정보 status

• 반환 유형: RecordStatus

  없음

• 설명: 일치된 레코드의 수명 주기 상태를 반환합니다.

등록 정보 timestamp

• 반품 유형: str

  없음

• 설명: 가능한 경우 레코드 시간 기록을 반환합니다.