데이터 스토어 검색 구성

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

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

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

검색 조건 입력

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

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

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

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

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

부스트 사양

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

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

주요 필드:

• condition: (문자열) 부스트가 적용되는 시점을 지정하는 표현식입니다. 표준 필터 표현식 구문을 사용합니다. Dialogflow 표현식을 사용하여 $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를 직접 호출하는 경우 전체 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은 AI Applications의 필터 표현식 문법을 따라야 합니다.
및 부스트 값은 -1.0에서 1.0 사이여야 합니다.

필터 사양

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

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

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

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

이 예에서 필터는 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은 AI Applications의 필터 표현식 문법을 따라야 합니다.

Dialogflow 동적 표현식

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

BoostSpec 조건과 FilterSpec 문자열 모두 Dialogflow 표현식을 통합하여 동적으로 만들 수 있습니다. 이를 통해 진행 중인 대화에서 가져온 컨텍스트 데이터를 기반으로 검색 동작을 맞춤설정할 수 있습니다. 동적 표현식은 직접 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 표현식으로 평가됩니다. 결과 필터 문자열은 각각 데이터 스토어의 FilterSpecs 객체를 만드는 데 사용되며 이 객체는 SearchConfig에도 추가됩니다.
3. 이렇게 동적으로 구성된 SearchConfig는 데이터 스토어로 전송되는 검색 요청의 QueryParameters에 포함됩니다.

검색 조건 구성

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

• 기존 대화형 에이전트 (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 Messenger 구성

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이 유효하지만 기본 검색 서비스에 따라 잘못된 SearchConfig가 발생하는 경우 (예: 매개변수 대체 후 잘못된 조건 문자열) 검색 서비스는 오류를 반환합니다.

런타임 대체 오류

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

컴파일된 SearchConfig 검토

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

다음 단계

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