데이터 스토어 검색 구성

부스트 및 필터 사양을 구성하여 Dialogflow CX 데이터 스토어 도구에서 검색된 검색 결과에 영향을 줄 수 있습니다. 이렇게 하면 에이전트가 데이터 스토어를 사용하여 정보를 찾을 때 더 맞춤설정되고 컨텍스트를 인식하는 상호작용을 할 수 있습니다.

원하는 경우 동적 표현식을 포함하여 대화 컨텍스트를 기반으로 결과를 미세 조정할 수 있습니다. 예를 들어 에이전트가 최종 사용자가 '휴대전화'를 소유하고 있음을 나타내는 정보를 캡처했습니다. 대화 후반부에 '음성사서함을 어떻게 확인하나요?'와 같은 일반적인 질문에 답변할 때 휴대전화와 관련된 문서를 부스트하도록 데이터 스토어 도구를 구성할 수 있습니다.

콘솔, API 또는 Dialogflow CX 메신저 통합을 사용하여 데이터 스토어 검색 결과를 구성할 수 있습니다.

검색 조건 입력

SearchConfig 객체에서 부스트 사양 (BoostSpec) 및 필터 사양 (FilterSpec) 필드를 사용하여 검색 결과를 구성합니다. 이러한 구성은 도구 내의 데이터 스토어별로 적용되므로 연결된 각 데이터 스토어의 작동 방식을 제어할 수 있습니다.

콘솔을 사용하거나 직접 API 호출을 전송하는 두 가지 방법 중 하나로 검색 조건을 구성할 수 있습니다.

두 가지 사이에는 중요한 차이점이 있습니다.

• API 호출: DetectIntent API 호출을 사용하여 SearchConfig에서 BoostSpec 및 FilterSpec를 전송합니다. 요청에 전체 SearchConfig 객체를 제공해야 합니다. 직접 API 호출로 전송된 SearchConfig는 항상 콘솔을 사용하여 전송된 SearchConfig를 재정의합니다. 동적 표현식 및 매개변수 참조는 지원되지 않습니다.

• 콘솔: 콘솔은 BoostSpec 및 FilterSpec 구성을 사용하여 검색 요청과 함께 전송하는 SearchConfig 객체를 구성합니다. 원하는 경우 매개변수 참조와 동적 표현식을 포함하여 대화에서 기록된 문맥 데이터에 맞게 결과를 조정할 수 있습니다. 전체 SearchConfig 객체가 아닌 FilterSpecs를 구성하려면 ConditionBoostSpec 객체와 필터 문자열 목록만 제공하면 됩니다.

최종 사용자 정보는 detectIntentRequest에서 JSON으로 제공됩니다. 예상 스키마가 없으므로 객체 속성을 정의할 수 있습니다.

부스트 사양

부스트 사양을 사용하면 특정 문서에 부스트 값을 적용하여 검색 결과 순위를 변경할 수 있습니다. 단일 데이터 스토어에 여러 부스트 사양을 추가할 수 있습니다.

각 부스트 사양을 단일 ConditionBoostSpec 객체를 나타내는 JSON 문자열로 입력합니다.

주요 필드:

• condition: (문자열) 부스트를 적용할 시기를 지정하는 표현식입니다. 표준 필터 표현식 문법을 사용합니다. Dialogflow CX 표현식을 사용하여 $session.params.YOUR_PARAM_NAME 또는 $request.end-user-metadata.YOUR_KEY과 같이 결과를 동적으로 만들 수 있습니다.
• boost: (숫자) 부스트 강도를 결정하는 -1.0에서 1.0 사이의 값입니다.
  • 양수 값은 일치하는 문서를 승격합니다. 값이 1.0이면 해당 항목의 순위가 크게 높아집니다.
  • 음수 값은 일치하는 문서의 순위를 내립니다. -1.0 값은 강한 순위 내리기를 제공합니다.
  • 0.0 값은 부스트를 적용하지 않으며 허용되지 않습니다.
• boostControlSpec: 조건과 부스트의 기본 조합보다 맞춤설정된 순위에 대한 더 많은 제어를 제공합니다. 이 필드 구성에 대한 자세한 내용은 참고 문서를 확인하세요.

콘솔 입력 예시:

콘솔에서 에이전트를 구성하는 경우 다음 형식으로 ConditionBoostSpecs 목록을 제공합니다.

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

참고: 이 예시에서는 URI가 $session.params.doc_id 세션 파라미터 값과 일치하는 문서가 0.5 강도로 부스팅됩니다.

API 입력 예시:

API를 직접 호출하는 경우 전체 SearchConfig 객체에 ConditionBoostSpecs를 제공해야 합니다. 다음 검색 구성은 부스트 사양을 설명합니다.

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

참고: DATASTORE_ID는 데이터 스토어(projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name)의 전체 이름이며,
CONDITION은 에이전트 검색의 필터 표현식 문법을 따라야 하고,
부스트 값은 -1.0~1.0 사이여야 합니다.

필터 사양

필터 사양은 정의된 기준과 일치하는 문서만 포함하도록 검색 결과를 제한합니다. 단일 데이터 스토어에 여러 필터 사양을 추가할 수 있습니다.

각 필터 사양은 문자열 표현식으로 입력해야 합니다. 문자열은 표준 필터 표현식 문법을 준수해야 합니다. 이 문자열 내에서 Dialogflow CX 표현식을 사용하여 $session.params.YOUR_PARAM_NAME 또는 $request.end-user-metadata.YOUR_KEY과 같은 동적 결과를 만들 수 있습니다.

콘솔 필터 사양 문자열 예시:

콘솔을 사용하여 에이전트를 구성하는 경우 filter 문자열 목록을 제공하여 FilterSpec 객체를 형성해야 합니다.

이 예시에서 필터는 numeric_field가 $session.params.min_value 값보다 크거나 같고 stock_availability가 "IN_STOCK"인 문서만 반환합니다.

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

API 필터 구성 예시:

API를 직접 호출하는 경우 전체 SearchConfig 객체에 filter 문자열을 제공해야 합니다.

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

참고: DATASTORE_ID는 데이터 스토어(projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name)의 전체 이름이며,
CONDITION은 Agent Search의 필터 표현식 문법을 따라야 합니다.

Dialogflow CX 동적 표현식

참고: 동적 표현식은 데이터 스토어 도구에만 사용할 수 있습니다. 데이터 스토어 핸들러에는 사용할 수 없습니다.

BoostSpec 조건과 FilterSpec 문자열 모두 Dialogflow CX 표현식을 통합하여 동적으로 만들 수 있습니다. 이를 통해 진행 중인 대화에서 검색된 문맥 데이터를 기반으로 검색 동작을 맞춤설정할 수 있습니다. 동적 표현식은 직접 API 호출에서 지원되지 않으며 콘솔을 사용하여 구성하는 경우에만 사용할 수 있습니다.

대화 문맥 데이터에 액세스하는 방법은 두 가지입니다.

• 세션 파라미터: $session.params.YOUR_PARAMETER_ID를 사용하여 대화 중에 수집된 값입니다.
• 최종 사용자 메타데이터: $request.end-user-metadata.YOUR_KEY를 사용하여 DetectIntentRequest에 전달된 최종 사용자에 대한 메타데이터입니다. 이 옵션을 사용하려면 end_user_metadata가 DetectIntent 호출의 QueryParameters에 포함되어 있는지 확인하세요. 자세한 내용은 endUserMetadata를 참조하세요.

사용 가능한 시스템 함수 및 표현식 문법에 대한 자세한 내용은 조건 및 시스템 함수 참조를 확인하세요.

런타임 시 적용되는 검색 조건

데이터 스토어 도구가 검색을 실행하는 경우:

1. 부스트 사양에 제공한 JSON 문자열을 평가합니다. 각 유효한 JSON 문자열은 ConditionBoostSpec 객체로 변환됩니다. 그런 다음 특정 데이터 스토어 연결을 위해 BoostSpecs 객체로 그룹화되고 전체 SearchConfig에 추가됩니다.
2. 필터 사양에 제공한 문자열을 Dialogflow CX 표현식으로 평가합니다. 각 결과 필터 문자열은 데이터 스토어의 FilterSpecs 객체를 만드는 데 사용되며, 이 객체는 SearchConfig에도 추가됩니다.
3. 데이터 스토어로 전송되는 검색 요청의 QueryParameters에 이 동적으로 구성된 SearchConfig를 포함합니다.

검색 조건 구성

검색 조건을 구성하려면 다음 기본 요건을 완료했는지 확인하세요.

• 기존 Dialogflow CX 에이전트
• 하나 이상의 데이터 스토어가 사용 설정된 에이전트에 구성된 데이터 스토어 도구

Console 구성

1. 대화형 에이전트 콘솔을 열고Google Cloud 프로젝트를 선택합니다.
2. 드롭다운 메뉴에서 에이전트를 선택합니다.
3. 왼쪽 메뉴로 이동하여 도구를 클릭합니다. 구성하려는 데이터 스토어 도구를 선택합니다.
4. 도구 수정 페이지에서 데이터 스토어 섹션으로 이동합니다. 수정할 데이터 스토어 옆에 있는 설정 아이콘 (⚙️)을 클릭합니다.
5. 데이터 스토어 구성 메뉴가 표시됩니다. 여기에서 부스트 사양과 필터 사양을 추가하여 검색 결과를 수정할 수 있습니다.
   • 부스트 사양의 경우 ConditionBoostSpec를 정의하는 JSON 객체를 제공합니다. 자세한 내용은 부스트 사양을 참조하세요.
   • 필터 사양의 경우 필터 기준을 정의하는 문자열을 제공합니다. 자세한 내용은 필터 사양을 참고하세요.
6. 사양을 추가하고 구성한 후 측면 패널 하단에서 확인을 클릭합니다.
7. 데이터 스토어 도구 수정 페이지에서 저장을 클릭하여 변경사항을 저장합니다.

API 구성

인텐트 인식 요청을 전송할 때 Dialogflow CX에 검색 구성 데이터를 제공할 수 있습니다. 이 정보는 세션에 지속되지 않기 때문에 모든 인텐트 인식 요청에 제공되어야 합니다.

Sessions.detectIntent 메서드의 queryParams.searchConfig 필드에 이 정보를 제공합니다.

Session API 참조로 이동

세션 참조의 프로토콜 및 버전을 선택합니다.

프로토콜	V3	V3beta1
REST	세션 리소스	세션 리소스
RPC	세션 인터페이스	세션 인터페이스
C++	SessionsClient	해당 사항 없음
C#	SessionsClient	해당 사항 없음
Go	SessionsClient	해당 사항 없음
자바	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	없음	해당 사항 없음
Python	SessionsClient	SessionsClient
Ruby	없음	해당 사항 없음

닫기

Dialogflow CX 메신저 구성

Dialogflow CX 메신저 통합에 검색 구성 데이터를 제공할 수 있습니다. 자세한 내용은 setContext 메서드를 참고하세요.

검색 사양 또는 검색 구성을 적용하려면 웹사이트에 Dialogflow CX 메신저 코드를 삽입할 때 다음 스니펫을 추가해야 합니다.

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

자세한 내용은 setQueryParameters 메서드를 참조하세요.

문제 해결

다음 솔루션은 구성 중에 발생하는 몇 가지 일반적인 문제를 해결합니다. 다양한 세션 파라미터와 최종 사용자 메타데이터 값을 트리거하는 대화를 시뮬레이션하여 구성을 철저히 테스트합니다.

잘못된 표현식

부스트 사양 조건 또는 필터 사양 문자열에 잘못된 Dialogflow CX 표현식 (예: 잘못된 문법 또는 존재하지 않는 매개변수 참조)이 포함된 경우 표현식 컴파일이 실패합니다. 표현식 컴파일과 관련된 오류는 일반적으로 diagnostic_info 필드 내의 DetectIntentResponse에서 SystemFunctionResults로 반환됩니다.

잘못된 ConditionBoostSpec JSON

대화형 에이전트 콘솔은 ConditionBoostSpec JSON 문자열을 저장할 때 유효한 JSON인지, 구조를 ConditionBoostSpec 객체에 매핑할 수 있는지 확인하기 위해 몇 가지 검증을 수행합니다. JSON이 유효하지만 기본 Google 검색 서비스에 따라 잘못된 SearchConfig가 발생하는 경우 (예: 매개변수 대체 후 잘못된 조건 문자열) Google 검색 서비스에서 오류를 반환합니다.

런타임 대체 오류

ConditionBoostSpec JSON 문자열이 유효하고 파싱 가능하지만 필드 내에서 Dialogflow CX 표현식의 런타임 대체 중에 오류가 발생하는 경우 (예: 조건 문자열) 이러한 오류는 diagnostic_info에서 SystemFunctionResults로 보고됩니다.

컴파일된 SearchConfig 검토

쿼리가 실행될 때 적용되는 SearchConfig는 응답의 search_signals에서 사용할 수 있습니다. SearchConfig를 검토하면 여기에 설명되지 않은 추가 문제에 대한 유용한 정보를 얻을 수 있습니다.

다음 단계

• SearchConfig 및 구성요소의 구조에 대한 자세한 내용은 search_config 문서를 참조하세요.
• 표현식 문법에 대한 자세한 내용은 Dialogflow CX 조건 및 시스템 함수 참조를 확인하세요.
• 검색의 필터 표현식 구문에 대한 자세한 내용은 결과 필터링 및 순서를 참조하세요.