검색

이 페이지에서는 개발자 관련 범위 지정 도우미와 구체적인 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 계층별 검색 범위 분석

사례	스레드 검색()	Oracle 에이전트 메모리 검색()	저장 검색()
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와 함께 사용합니다. 대신 공정 기본값을 원하는 경우 필드를 생략합니다.

범위

클래스 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_일치

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

• 유형: bool

정확한_스레드_일치

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

• 유형: bool

결과

클래스 oracleagentmemory.core.OracleSearchResult

기준: SearchResult

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

• 매개변수:
  • distance float – 쿼리 벡터로부터의 거리입니다(더 작을수록 좋습니다).
  • record Record – 지속된 항목에 대한 메타데이터 정보를 포함하는 레코드 객체입니다.
  • id str | None – 저장된 레코드와 연관된 선택적 식별자입니다.

등록 정보 content

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

등록 정보 formatted_content

• 반품 유형: str

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

• 반환: 검색 결과에 대한 기본 표시 필드가 포함된 XML 안전 렌더링입니다.
• 반환 유형: str

재산 id

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

등록 정보 metadata

• 반품 유형: dict[str, Any] | None
• 설명: 레코드 메타데이터(사용 가능한 경우)를 반환합니다.

등록 정보 record

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

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

등록 정보 timestamp

• 반품 유형: str | None
• 설명: 가능한 경우 레코드 시간 기록을 반환합니다.