데이터 스토어 검색 구성

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

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

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

검색 조건 입력

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

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

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

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

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

부스트 사양 (부스트 사양)

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

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

주요 필드:

• 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 제공해야 합니다.

이 예에서는 $session.params.doc_id 세션 매개변수의 값과 일치하는 URI가 있는 문서가 0.5의 강도로 부스트됩니다. 이 형식의 JSON

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

API 입력 예:

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

"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는 에이전트 검색의 필터 표현식 문법을 따라야 합니다.

Dialogflow CX 동적 표현식

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

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

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

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

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

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

데이터 스토어 도구가 검색을 실행할 때 다음이 발생합니다.

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

검색 조건 구성

검색 조건을 구성하기 전에 다음이 있는지 확인하세요.

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

콘솔 구성

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 표현식 (예: 잘못된 문법 또는 존재하지 않는 매개변수 참조)이 포함되어 있으면 표현식 컴파일이 실패합니다. 표현식 컴파일과 관련된 오류는 일반적으로 DetectIntentResponse 내의 diagnostic_info 필드에서 SystemFunctionResults로 반환됩니다.

잘못된 ConditionBoostSpec JSON

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

런타임 대체 오류

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

컴파일된 SearchConfig 검토

쿼리가 실행될 때 적용되는 SearchConfig는 응답의 search_signals 에서 확인할 수 있습니다. SearchConfig를 검토하면 여기에 설명되지 않은 추가 문제를 파악할 수 있습니다.

다음 단계

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