대화형 상거래 에이전트 개발자 가이드

이 가이드에서는 Conversational API와 통합하여 고객에게 동적이고 AI 기반 채팅 환경을 제공하는 방법을 자세히 설명합니다. 다양한 질문 유형을 이해하고 API의 응답을 활용하면 관련 제품 검색을 제공하고, 고객 문의에 답변하고, 최종 사용자의 쇼핑 여정을 안내할 수 있습니다.

대화형 API의 conversationalFilteringMode를 사용하면 대화형 상거래 에이전트와 대화형 제품 필터링 간의 차이점을 명확하게 알 수 있습니다.

API 설정 및 호출 흐름

Conversational API는 대화형 상거래 에이전트를 지원합니다.

• gRPC: conversationalSearchService
• REST: conversationalSearch

대화형 API를 사용하면 사용자가 질문을 보내고 시스템이 텍스트 응답, 분류된 질문 유형, 잠재적인 세부 검색 옵션을 반환하는 채팅 환경을 사용할 수 있습니다.

이 API는 스트리밍 서비스로 작동하여 쿼리 의도를 조기에 감지할 수 있습니다. 대화의 후속 상호작용에는 conversation_id를 첨부해야 합니다.

검색 결과를 반환하려면 기존 Retail API를 Conversational API와 병렬로 호출해야 합니다.

최종 사용자가 보낸 질문

이 섹션에서는 대화형 상거래 에이전트 환경을 시작하는 방법을 설명합니다. 예를 들어 사용자가 검색창에 파티 계획 세워 줘라고 입력할 수 있습니다.

상거래를 위한 Vertex AI Search에 요청 보내기

두 가지 API 엔드포인트가 있습니다.

1. 대화형 API를 사용하여 대화형 환경을 가져와야 합니다.
2. 검색 결과를 가져오려면 핵심 Search API를 사용해야 합니다.

엔드포인트 1: 대화형 API 요청

• 사용자의 입력을 query로 설정하여 대화형 상거래 에이전트 요청을 만들어야 합니다.
• 요청은 projects/*/locations/*/catalogs/*/placements/*:conversationalSearch 엔드포인트로 HTTP POST 요청으로 전송되어야 합니다.

HTTP 메서드 및 엔드포인트

  POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
  

대화형 API 요청:

초기 질문

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}

• placement: 게재위치의 리소스 이름입니다 (예: projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). 이는 경로 매개변수이며 필수입니다.
• query: 사용자의 원시 검색어입니다. 필수입니다.
• branch: 브랜치 리소스 이름(예: projects/P/locations/L/catalogs/C/branches/B) 설정하지 않으면 default_branch이 사용됩니다. 필수입니다.
• visitorId: 방문자를 추적하는 고유 식별자입니다. 필수입니다.
• conversationId: 대화 세션을 추적하기 위한 고유 ID입니다. 새 대화의 initial 요청의 경우 이 필드는 비어 있어야 합니다. 동일한 대화 내의 후속 요청의 경우 이전 ConversationalSearchResponse에서 수신한 conversation_id로 설정해야 합니다.
• searchParams: (선택사항) filter, canonicalFilter, sortBy, boostSpec과 같은 표준 핵심 검색 매개변수입니다. LLM 대답과 표시되는 제품 검색 결과 간의 일관성을 유지하려면 이러한 파라미터가 핵심 Search API 호출에 사용된 구성을 반영해야 합니다.
• userInfo: (선택사항) 향상된 맞춤설정을 위한 사용자 정보입니다. userId, user_agent, direct_user_request (불리언)를 포함할 수 있습니다.
• conversationalFilteringSpec: (선택사항) 대화형 필터링 모드를 지정합니다. 설정하지 않으면 기본값은 DISABLED입니다.

  mode: 다음 세 가지 모드 중 하나를 사용하여 대화형 API를 통합하여 대화형 제품 필터링을 제어합니다.

• DISABLED: 이 모드에서는 클라이언트가 대화형 상거래 에이전트 검색만 구현합니다. 대화형 상거래 상담사 검색에 관한 이 구현 가이드에서는 이 모드를 사용하는 것이 좋습니다.

샘플 API 요청

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }
      

샘플 API 응답

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
      

• ENABLED: 이 모드에서 클라이언트는 대화형 상거래 에이전트 검색 및 대화형 제품 필터링을 포함한 모든 대화형 기능을 구현합니다.

대화형 제품을 모두 통합하는 방법에 관한 추가 가이드를 참고하세요.

샘플 API 요청

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }
      

샘플 API 응답

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
      

• CONVERSATIONAL_FILTER_ONLY: 선택한 경우 클라이언트는 대화형 제품 필터링을 만 구현합니다. 이 모드를 선택하면 사용자는 LLM 답변, 질문 분류 또는 추천 검색어를 생성하지 않고 대화형 제품 필터링만 경험합니다.

자세한 내용은 대화형 제품 필터 개발자 가이드를 참고하세요.

엔드포인트 2: 핵심 검색 API 요청

웹 인터페이스에 검색 결과를 표시하는 방법에는 두 가지가 있습니다.

옵션 1: 항상 검색 결과 표시

사용자 경험 디자인에 따라 채팅 옆의 전용 검색 결과 영역과 같이 대화형 출력과 관계없이 검색 결과가 항상 표시되어야 하는 경우 대화형 API 호출과 함께 사용자의 원래 질문을 핵심 제품 검색 API에 전송하세요. 이렇게 하면 제품 등록정보를 즉시 사용할 수 있습니다.

옵션 2: 대화형 출력을 기반으로 검색 결과 표시

사용자 환경 디자인이 더 동적이고 Conversational API의 응답에 따라 검색 결과만 표시하려는 경우(예: SIMPLE_PRODUCT_SEARCH 질문에 대해서만 또는 refined_search 추천이 제공될 때마다) 핵심 제품 검색 API에 질문을 보내기 전에 Conversational API의 응답을 기다리세요. 대답이 있는 경우 제공된 refined_search 쿼리를 사용하여 제품 결과를 가져옵니다.

선택한 사용자 인터페이스 옵션과 관계없이 실제 제품 결과를 가져와야 하는 경우 Retail API를 호출하면 됩니다. 자세한 내용은 사용자 의도 분류 및 소매업체 작업 이해하기를 참고하세요.

HTTP 메서드 및 엔드포인트

    POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search
    

핵심 제품 검색 API 요청:

초기 질문

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
    

• placement (필수): Retail Search 서빙 구성 또는 기존 게재위치의 리소스 이름입니다. 예를 들면 projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search입니다.
• query: 필수입니다. 검색어입니다. 사용자의 원시 입력(예: 파티 계획을 도와줘) 또는 Conversational Commerce API 응답에서 가져온 더 최적화된 refinedSearch.query(예: 파티 용품, 장식)일 수 있습니다.
• visitorId: 필수입니다. 방문자 추적을 위한 고유 식별자입니다. 이는 동일한 최종 사용자에 대해 Conversational Commerce API로 전송된 visitorId와 일치해야 합니다.
• branch(필수): 브랜치 리소스 이름입니다(예: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch).
• pageSize (선택사항): 반환할 최대 제품 수입니다.
• filter (선택사항): 검색 결과를 필터링하는 데 사용됩니다. 여기에서 일관성을 위해 대화형 커머스 API에 `searchParams` 로 전송하는 내용을 반영하는 필터를 적용합니다.
• orderBy (선택사항): 제품이 반환되는 순서를 지정합니다 (예: 관련성 또는 가격별).
• userInfo (선택사항): 맞춤설정을 위한 사용자 정보입니다. Conversational Commerce API 호출과 일치해야 합니다.
• searchMode (선택사항): 검색 동작을 정의합니다. PRODUCT_SEARCH는 일반적인 제품 질문에 사용됩니다.

응답 이해

이 코드 샘플은 Conversational Commerce API의 응답을 보여줍니다.

API 응답 (ConversationalSearchResponse)에는 query_types, conversational_text_response (해당하는 경우), refined_search 옵션이 포함되며 followup_question 또는 conversational_filtering_result가 포함될 수도 있습니다. conversation_id은 세션을 계속하는 데 필수적입니다.

상거래를 위한 Vertex AI Search의 응답

이 코드 샘플은 Conversational API 응답을 보여줍니다.

초기 응답

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }
    

소매업체가 응답으로 수행할 작업 (일반)

응답에서 다음 필드를 렌더링합니다.

• user_query_types: 이 필드는 사용자의 의도 분류를 제공합니다. 이러한 유형에 따른 자세한 작업은 사용자 의도 분류 및 소매업체 작업 이해하기를 참고하세요.
• conversation_id: 이 고유 ID를 브라우저 세션 저장소 또는 유사한 클라이언트 측 저장소에 저장하여 서버와의 대화형 세션을 유지할 수 있습니다. 이는 단일 쇼핑객에 대해 진행 중인 여러 대화를 구분하는 데 중요합니다. 모델은 지정된 conversation_id의 컨텍스트를 유지합니다. 새 conversation_id을 보내면 새 세션이 시작됩니다. 활동이 없는 시간(예: 30분)과 같은 세션 기간을 정의하는 것이 좋습니다.
• refined_search: 관련 검색 결과를 가져오는 데 사용되는 제안된 세부 검색어 목록입니다. SIMPLE_PRODUCT_SEARCH의 경우 항상 단일 쿼리입니다. LLM 답변을 찾는 다른 질문의 경우 하나 이상입니다. refined_search 쿼리는 핵심 Search API (SearchService.Search) 호출에 사용하거나 사용자에게 추천으로 표시할 수도 있습니다.
• conversational_text_response: 이 텍스트를 사용자에게 질문에 대한 기본 AI 생성 응답으로 표시합니다.
• followup_question: (선택사항) followup_question이 표시됩니다.
• state: 이 필드는 응답 생성 상태 ("STREAMING" 또는 "SUCCEEDED")를 나타냅니다. "SUCCEEDED"까지 로드 표시기를 표시하는 등 사용자 환경 피드백에 사용할 수 있습니다. 자세한 내용은 다음 섹션을 참고하세요.

스트리밍 API 이해

Conversational Commerce API는 스트리밍 서비스로 작동합니다. 즉, 사용자는 단일의 완전한 페이로드가 아닌 여러 청크로 응답의 일부를 수신합니다.

• 스트리밍을 사용하는 이유 LLM 텍스트 생성에는 시간이 걸릴 수 있습니다. 스트리밍을 사용하면 더 빠르게 대응할 수 있습니다.
• 첫 번째 응답 청크 (즉시):

• userQueryTypes 및 refinedSearch 쿼리를 포함합니다.
• state: "STREAMING"
• 후속 청크:

• conversationalTextResponse가 생성되는 동안 conversationalTextResponse의 일부를 포함합니다.
• 마지막 청크:

• 전체 conversationalTextResponse를 포함합니다.
• state: "SUCCEEDED"
• 실행 가능한 유용한 정보: 첫 번째 청크에서 사용자의 의도를 즉시 파악하고 AI 텍스트 응답이 아직 로드되는 동안 병렬로 제품 결과를 가져오기 시작할 수 있습니다.

대답의 첫 번째 청크에는 query_types 및 refined_search 쿼리가 포함되며 state는 STREAMING로 표시됩니다. 의도를 조기에 감지하고 검색 세부검색을 즉시 사용할 수 있으므로 모델은 사용자의 질문을 처리하는 방법과 LLM 응답의 지연 시간과 관련된 사용자 환경을 관리하는 방법을 신속하게 결정할 수 있습니다.

• SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT과 같이 대화형 텍스트 응답을 기대하지 않는 질문 유형의 경우:
• query_types이 첫 번째 청크에 있으므로 시스템은 LLM 대답이 나오지 않는다는 것을 즉시 알 수 있습니다. 추가 대화형 출력을 기다리지 않고 정적 메시지 표시, 지원팀으로의 리라우팅과 같은 이러한 유형에 대해 사전 정의된 처리를 진행할 수 있습니다.
• 특히 SIMPLE_PRODUCT_SEARCH의 경우 시스템은 첫 번째 청크에서 수신된 refined_search 쿼리를 사용하여 핵심 검색 API를 직접 호출할 수 있습니다. 이렇게 하면 검색 결과가 최소한의 지연으로 표시되어 일반적인 검색 환경 SLA를 충족할 수 있습니다.
• INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT와 같이 대화형 텍스트 응답을 기대하는 질문 유형의 경우:
• 초기 청크에서 query_types 및 refined_search 쿼리를 수신합니다. 이러한 refined_search 쿼리를 사용하여 핵심 검색 API에 대한 병렬 호출을 즉시 시작하여 제품 결과를 로드할 수 있습니다.
• 후속 청크는 대화형 텍스트 응답의 여러 섹션을 포함하여 스트리밍됩니다. 이 기간 동안 state는 "STREAMING"로 유지됩니다.
• 마지막으로 마지막 청크에는 완전한 대화형 텍스트 응답이 포함되며 state가 "COMPLETED"로 변경됩니다.
• 이 스트리밍 방식을 사용하면 AI 요약이 생성되는 동안 검색 결과가 로드되기 시작하는 유연한 최종 사용자 환경을 제공할 수 있습니다. 대화형 답변의 로드 표시기를 표시하거나 대화형 답변이 완전히 스트리밍된 후에 표시할 수 있습니다.

사용자 의도 분류 및 소매업체 작업 이해

인텐트 분류기는 사용자 쿼리를 처리하는 방법과 시작할 대화 모드를 결정합니다.

대답의 query_types 필드는 사용자 의도의 분류를 나타내는 목록입니다. 시스템에서 다음과 같이 처리해야 합니다. conversational_text_response는 API에서 생성된 AI 자연어 응답을 나타냅니다.

userQueryTypes 필드 (첫 번째 응답 청크)는 애플리케이션의 다음 작업을 결정하는 데 가장 중요한 필드입니다.

• SIMPLE_PRODUCT_SEARCH: 빨간색 드레스
  • API 응답: conversational_text_response 없음 단일 refinedSearch 쿼리를 반환합니다.
  • 내 조치: refinedSearch.query를 사용하여 Search API를 즉시 호출합니다. 표준 검색 결과 페이지로 전환하거나 결과를 표시합니다.
• INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT: 파티 계획
  • API 응답: conversationalTextResponse, refinedSearch 쿼리를 제공하며 followupQuestion를 제공할 수도 있습니다.
  • 내 작업: AI 텍스트 응답을 표시합니다. refinedSearch 쿼리를 사용하여 제품 캐러셀 또는 추천을 채웁니다. followupQuestion를 표시합니다.
• 지원 쿼리: ORDER_SUPPORT 및 STORE_RELEVANT을 포함합니다.
  • API 응답: conversational_text_response 없음
  • 내 조치: 사용자를 주문 추적, 매장 찾기와 같은 적절한 페이지로 리디렉션하거나 미리 작성된 응답을 표시합니다.

대화형 상거래 에이전트는 검색어 카테고리를 사용하여 LLM 기반 답변이 생성되는지 여부와 이러한 시나리오에서 최종 사용자 쿼리가 대화형 및 검색 API에 의해 처리되는 방식을 결정합니다.

카테고리	질문 분류
1. LLM 답변이 필요하지 않은 관련 없는 질문	QUERY_TYPE_UNSPECIFIED: 지정되지 않은 쿼리 유형입니다. RETAIL_IRRELEVANT: 소매 도메인과 관련이 없는 질문입니다(예: 적대적 질문(폭탄 만드는 방법), 대화형 질문(잘 지내?), 브레이크아웃 질문(시를 써 줘)). BLOCKLISTED: 상거래 고객이 명시적으로 차단한 질문 (예: 애드빌의 부작용은 무엇인가요?)
2. 지원 및 정보 관련 질문	ORDER_SUPPORT: 부수적인 질문 또는 지원 질문 (예: 주문 추적, 주문 12345 상태) DEALS_AND_COUPONS: 특가, 프로모션, 제품 특가, 할인과 관련된 질문 (예: 추수감사절 특가가 있나요?) STORE_RELEVANT: 영업시간, 제품 재고 여부 (예: 우유 재고가 있나요?) 등 매장 위치와 관련된 질문 RETAIL_SUPPORT: 결제 수단(어떤 결제 수단을 허용하시나요?)을 비롯한 구매와 관련된 질문
3. LLM이 필요하지 않은 키워드 검색 대화형 API 요청: 초기 질문 { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "show me some monster energy drinks", "visitorId": "test" } 대화형 API 응답: 초기 응답 { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } 검색 API 요청: 후속 질문 { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: 빨간색 드레스 또는 몬스터 음료를 보여줘와 같은 기본 제품 검색
#4. LLM 답변 찾기 질문 대화형 API 요청: 초기 질문 { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Compare 1% milk with 2% milk", "visitorId": "test" } 대화형 API 응답: 초기 응답 { "userQueryTypes": ["PRODUCT_COMPARISON"], "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.", "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba", "refinedSearch": [ { "query": "1% milk" }, { "query": "2% milk" } ] } 검색 API 요청: 후속 질문 { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	PRODUCT_DETAILS: 사용자가 [제품 이름]의 사양을 보여 줘, 2% 우유의 단백질 함량은 얼마야?와 같은 제품 세부정보와 사양을 찾고 있습니다. PRODUCT_COMPARISON: 제품 비교(예: [제품 이름] 과 [제품 이름] 비교, 1% 우유와 2% 우유 비교) BEST_PRODUCT: 패턴이 가장 많이 일치하는 질문(예: 가장 건강한 쿠키는 무엇인가요? 어떤 우유 브랜드가 가장 좋은가요?
#5. 의도 상세검색 대화형 API 요청: 초기 질문 { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Help me plan a party", "visitorId": "test" } 대화형 API 응답: 초기 응답 { "userQueryTypes": ["INTENT_REFINEMENT"], "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.", "followupQuestion": { "followupQuestion": "What kind of party are you planning?" }, "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", "refinedSearch": [ { "query": "Decorations" }, { "query": "Snacks" }, { "query": "Party Supplies" }, { "query": "Drinks" }, { "query": "Cake" } ], "state": "SUCCEEDED" }	INTENT_REFINEMENT: 유형이 명확하지 않으며 파티 계획을 도와줘.와 같이 유형을 명확히 하기 위한 후속 대화나 구체화가 필요할 수 있습니다. 이는 대화에서 가장 인기 있는 인텐트인 경우가 많습니다.

카테고리 1. LLM 답변이 필요하지 않은 관련성 없는 질문

• QUERY_TYPE_UNSPECIFIED:
• conversational_text_response가 제공되지 않습니다.
• 작업: 기본 또는 오류 케이스로 처리합니다. 사용자에게 명확한 설명을 요청하거나 일반적인 도움을 받을 수 있는 곳으로 안내할 수 있습니다.
• RETAIL_IRRELEVANT:
• conversational_text_response가 제공되지 않습니다.
• 작업: 애플리케이션의 설계에 정의된 대로 질문에 답변할 수 없습니다 또는 저는 쇼핑 도우미입니다. 무엇을 도와드릴까요?와 같은 적절한 메시지를 표시하여 이를 처리합니다.
• BLOCKLISTED:
• conversational_text_response이 제공되지 않습니다.
• 작업: 차단 목록 정책에 따라 처리합니다. 일반적으로 일반적인 이 요청을 처리할 수 없습니다 메시지를 표시합니다.

카테고리 2 지원 및 정보 쿼리

이러한 유형의 경우 API는 기본적으로 직접 conversational_text_response를 제공하지 않지만 올바른 링크나 리소스로 연결하는 옵션이 있습니다.

• ORDER_SUPPORT:
• 기본 작업: conversational_text_response이 제공되지 않습니다. 웹 인터페이스에 표준 메시지, 관련 링크를 표시하거나 쿼리를 자체 전용 지원 API 또는 고객 서비스 채널로 리디렉션해야 합니다.
• DEALS_AND_COUPONS:
• 기본 작업: conversational_text_response이 제공되지 않습니다. 웹 인터페이스에 표준 메시지, 관련 링크를 표시하거나 딜 또는 프로모션 시스템으로 쿼리를 리디렉션해야 합니다.
• STORE_RELEVANT:
• 기본 작업: conversational_text_response이 제공되지 않습니다. 웹 인터페이스에 표준 메시지, 관련 링크를 표시하거나 쿼리를 자체 매장 찾기 또는 정보 시스템으로 리디렉션해야 합니다.
• RETAIL_SUPPORT:
• 기본 작업: conversational_text_response이 제공되지 않습니다. 웹 인터페이스에 표준 메시지, 관련 링크를 표시하거나 질문을 자체 자주 묻는 질문 및 정보 시스템으로 리디렉션해야 합니다.

카테고리 3 LLM 대답이 필요하지 않은 키워드 검색

• SIMPLE_PRODUCT_SEARCH:
• 대화형 텍스트 대답이 생성되지 않습니다.
• 작업: API 응답은 항상 단일 refined_search 쿼리를 반환합니다. 이 조정된 쿼리는 추천 검색어 역할을 합니다. 핵심 검색 API (SearchService.Search)를 직접 호출하고 원래 쿼리 또는 refined_search 쿼리를 사용하여 관련 제품 결과를 가져옵니다. refined_search.query는 현재 최종 사용자 입력에서 직접 가져오지 않을 수도 있지만 채팅 기록 컨텍스트에서 파생될 수도 있습니다. 예를 들어 최종 사용자가 이전에 파티 드레스를 빨간색으로 구체화한 경우 구체화된 질문은 빨간색 파티 드레스가 될 수 있습니다.
• 대화형 인터페이스 (예: 챗봇)의 경우: API에서 제공하는 refined_search.query를 사용하는 것이 매우 좋습니다. 대화형 흐름에서 '바나나를 찾는 데 도움을 줄 수 있어?'와 같은 자연어 질문은 API에 의해 정확한 제품 검색어 ('바나나')로 자동 최적화되어 관련성이 높은 제품 결과를 제공합니다.
• 핵심 검색 환경 (예: 검색 결과 페이지): 원래 검색어가 이미 정확한 제품 검색어일 가능성이 높으므로 API의 refined_search.query 또는 최종 사용자가 제공한 원래 검색어를 자유롭게 사용할 수 있습니다. 웹 인터페이스 및 검색 결과 표시 전략에 가장 적합한 옵션을 선택하세요.
• 사용자 환경 옵션: SIMPLE_PRODUCT_SEARCH 질문의 경우 대화를 종료할 필요가 없습니다. 사용자는 후속 요청에서 conversation_id을 전달하여 대화를 계속할 수 있습니다.
• 옵션 A: 대화형 웹 인터페이스 종료: 많은 소매업체는 SIMPLE_PRODUCT_SEARCH가 감지되면 사용자를 표준 검색 결과 페이지로 전환하여 채팅 창을 효과적으로 닫습니다. 이 시나리오에서 최종 사용자가 이전 conversation_id 없이 표준 검색창에 새 검색어를 입력하면 새롭고 별도의 대화로 처리되고 새 conversation_id가 발급됩니다.
• 옵션 B: 대화형 웹 인터페이스 계속: 소매업체는 채팅 창을 열어 둘 수 있습니다. 이렇게 하면 사용자가 대화 모드로 되돌아갈 수 있습니다. 옵션 A 또는 B를 구현할지는 전적으로 소매업체의 선호하는 사용자 환경에 따라 달라집니다.

검색어를 대화형 상호작용에 정확하게 기여 분석하고 커머스용 Vertex AI Search 내에서 전체 분석 기능을 사용하려면 적절한 이벤트 태그가 중요합니다.

1. conversation_id 가져오기 conversationalSearch API 호출을 하면 ConversationalSearchResponse.conversation_id가 반환됩니다.
2. 사용자 이벤트에 태그 지정 대화형 응답이 검색어로 이어지는 경우(예: 시스템이 SIMPLE_PRODUCT_SEARCH에 대한 구체화된 질문을 기반으로 검색을 자동으로 실행하는 경우) 후속 검색 사용자 이벤트(UserEvent)에 ConversationalSearchResponse에서 수신된 동일한 conversation_id을 태그해야 합니다.

UserEvent.conversation_id에 올바르게 태그를 지정하면 애널리틱스에서 이전 대화형 상호작용에 검색어를 정확하게 기여도 부여하여 사용자의 행동과 전환 경로에 대한 유용한 정보를 제공할 수 있습니다.

카테고리 4. LLM 답변 찾기 질문

이러한 질문 유형의 경우 API는 conversational_text_response (LLM 답변)을 생성하며 하나 이상의 refined_search 질문을 제공할 수도 있습니다. 대화가 종료되지 않으며 최종 사용자가 계속할 수 있습니다.

• PRODUCT_DETAILS:
• 작업: conversational_text_response에서 요청된 제품 세부정보를 제공합니다. 시스템은 이 정보를 사용자에게 명확하게 표시해야 합니다.
• 또한 응답에는 핵심 검색 API를 사용하여 검색 결과를 가져오는 데 사용해야 하는 refined_search (하나 이상의 추천 검색어, 순서 지정 및 순위 지정)가 포함됩니다.
• PRODUCT_COMPARISON:
• 작업: conversational_text_response는 지정된 제품을 비교합니다. 시스템은 이 정보를 사용자에게 명확하게 표시해야 합니다.
• 대답에는 핵심 검색 API를 사용하여 검색 결과를 가져오는 데 사용해야 하는 refined_search (하나 이상의 추천 검색어, 순서 지정 및 순위 지정)가 포함됩니다.
• BEST_PRODUCT:
• 작업: conversational_text_response는 질문과 가장 일치하는 제품에 관한 추천 또는 정보를 제공합니다. 시스템에 이 정보가 표시되어야 합니다.
• 대답에는 핵심 검색 API를 사용하여 검색 결과를 가져오는 데 사용해야 하는 refined_search (하나 이상의 추천 검색어, 순서 지정 및 순위 지정)가 포함됩니다.

카테고리 5 인텐트 수정

• INTENT_REFINEMENT:
• 작업: 대답에 conversational_text_response, followup_question, refined_search (하나 이상의 추천 검색어)이 포함됩니다. 권장되는 표시 순서는 다음과 같습니다.
1. conversational_text_response
2. refined_search 제안: 순서가 지정되고 순위가 매겨지므로 대답과 동일한 순서로 표시하는 것이 중요합니다.
3. Followup_question
• 대답에는 핵심 검색 API를 사용하여 검색 결과를 가져오는 데 사용해야 하는 refined_search (하나 이상의 추천 검색어, 순서 지정 및 순위 지정)가 포함됩니다.
• 후속 상호작용에서는 사용자의 답변을 conversation_id와 함께 전송합니다.

제품에 대한 추천 질문 표시

대화형 커머스 에이전트에서 질문과 제품 추천을 표시하도록 Google 검색을 구성하는 방법은 다음과 같습니다.

Conversational API가 refinedSearch 질문을 반환하면 이러한 질문은 최종 사용자를 관련 제품으로 안내할 수 있는 좋은 기회가 됩니다. 이는 카테고리 4 (LLM 답변 검색 질문) 및 카테고리 5 (INTENT_REFINEMENT)에 특히 유용합니다.

권장사항

• 디스플레이: 상위 N (웹 인터페이스에 적합한 숫자에 대한 테스트가 진행 중이므로 1~3) refinedSearch 질문을 사용자에게 표시합니다.
• 메커니즘: 이러한 추천 검색어는 백그라운드에서 또는 사용자 상호작용 시 핵심 검색 API (SearchService.Search)를 통해 실행해야 합니다.
• 프레젠테이션: 결과를 대화형 캐러셀 또는 클릭 가능한 카드로 표시하여 사용자가 관련 제품 카테고리 또는 특정 항목을 탐색할 수 있도록 합니다. 이를 통해 즉각적인 가치를 제공하고 대화형 상호작용과 제품 검색 간의 격차를 해소할 수 있습니다.

Search API 요청:

후속 질문

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}
  

상거래를 위한 Vertex AI Search에 전송할 이벤트

검색어를 대화형 상호작용에 정확하게 귀속시키고 적절한 이벤트 태그를 사용하여 커머스용 Vertex AI Search 내에서 전체 분석 기능을 사용하는 것이 중요합니다.

1. conversation_id 가져오기 conversationalSearch API 호출을 하면 ConversationalSearchResponse.conversation_id가 반환됩니다.
2. 사용자 이벤트에 태그 지정 대화형 대답이 검색어로 이어지는 경우(예: 최종 사용자가 클릭하는 refined_search 추천이 표시되는 경우) 또는 시스템에서 구체화된 질문을 기반으로 검색을 자동으로 실행하는 경우 후속 검색 사용자 이벤트(UserEvent)에 ConversationalSearchResponse에서 수신된 동일한 conversation_id를 태그해야 합니다.

UserEvent.conversation_id에 올바르게 태그를 지정하면 애널리틱스에서 검색어를 이전 대화형 상호작용에 정확하게 귀속시켜 사용자 행동과 전환 경로에 대한 유용한 정보를 제공할 수 있습니다.

대화 계속하기

이 섹션에서는 Conversational API가 Conversational Commerce 에이전트 세션을 유지하고 이 마지막 단계에서 계속되는 방법을 설명합니다.

Conversational API는 conversation_id를 사용하여 진행 중인 대화를 관리합니다. LLM 답변과 검색 결과 간의 일관성을 보장하려면 후속 Conversational API 요청에 핵심 검색 API 호출의 구성을 반영하는 SearchParams이 포함되어야 합니다.

테이블 보기

세션 처리	설명	대화형 API 통합
새 대화 시작하기	새 대화를 시작하기 위해 클라이언트는 API 요청에서 conversation_id를 생략합니다.	샘플 API 요청 placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" 샘플 API 응답 user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
대화 계속하기	Conversational API는 API 응답의 일부로 conversation_id를 반환합니다. 이 ID는 동일한 대화를 계속하기 위해 후속 요청에서 전송될 수 있습니다. 이렇게 하면 대화형 상거래 에이전트가 해당 세션의 대화 기록을 기반으로 사용자의 질문에 응답할 수 있습니다.	샘플 API 요청 placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" 샘플 API 응답 user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
검색 결과 일관성 보장	LLM 대답이 표시된 검색 결과와 일치하도록 하려면 클라이언트가 대화형 API 요청에서 SearchParams를 사용해야 합니다. 이러한 검색 매개변수는 핵심 검색 API와 동일한 구성을 가져야 합니다.	샘플 API 요청 placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

세션 처리

• 새 대화를 시작합니다.
  • 설명: 새 대화를 시작하려면 클라이언트가 API 요청에서 conversationId를 생략합니다.
  • 새 대화를 시작해야 하는 경우: 클라이언트는 다음과 같은 여러 일반적인 사용자 환경 시나리오에서 새 대화를 시작하여 API 응답에서 새로운 conversationId를 가져오려고 할 수 있습니다.
    • 새 탭 또는 세션: 고객이 새 브라우저 탭에서 사이트를 열거나 완전히 새로운 세션을 시작하는 경우입니다.
    • 새 원래 질문: 일부 UX 디자인에서는 고객이 관련 없는 새 질문을 입력하는 경우 가장 관련성 높은 컨텍스트를 보장하기 위해 대화 흐름을 다시 시작할 수 있습니다.
    • 대화 다시 시작 버튼: 웹 인터페이스에 명시적인 새 채팅 시작 또는 대화 재설정 버튼이 있는 경우 이 버튼을 클릭하면 새로운 대화 세션이 트리거됩니다.
  • 대화형 API 통합: API 응답에는 후속 요청에 사용되는 새로운 conversationId가 포함됩니다.
• 대화 계속하기:
  • 설명: Conversational API는 API 응답의 일부로 conversation_id를 반환합니다. 동일한 대화를 계속하려면 후속 요청에서 이 ID를 전송해야 합니다. 이렇게 하면 Conversational Commerce 에이전트가 해당 세션 내의 대화 기록을 기반으로 사용자의 질문에 응답하여 최종 사용자 query, conversational_text_response, followup_question를 처리할 수 있습니다.
  • 대화형 API 통합: 클라이언트는 이전 응답의 conversation_id를 ConversationalSearchRequest에 전달합니다.
• 검색 결과 일관성 보장:
  • 설명: LLM 대답이 사용자에게 표시되는 검색 결과와 일치하도록 하려면 클라이언트가 Conversational API 요청에서 searchParams를 사용해야 합니다. 이러한 검색 매개변수는 제품 결과를 가져오는 데 사용되는 Search API 호출과 동일한 구성(예: 필터, 정렬 순서)을 가져야 합니다.
  • 대화형 API 통합: ConversationalSearchRequest 내의 searchParams 객체는 핵심 제품 검색에 사용되는 SearchRequest과 동일하게 채워져야 합니다.

상거래를 위한 Vertex AI Search에 요청 보내기

세션 스토리지에서 conversation_id를 가져올 수 있습니다. 요청에는 이전 응답의 질문에 대한 답변일 수 있는 새 고객 query가 포함되어야 합니다. 최종 사용자가 구체화된 질문에 따라 행동하는 경우 요청에는 이전 응답의 가장 최근 refined_search.query도 포함되어야 합니다. 그렇지 않으면 완전히 새롭고 관련이 없는 질문과 conversationId를 포함해야 합니다. 항상 일관된 searchParams을 포함해야 합니다.

참고: 새 최종 사용자 질문에 대해 conversationId가 유지되는지 아니면 재설정되는지는 특정 UX 선택사항과 선택한 사용자 환경에 따라 다릅니다. conversationId는 지정된 대화 세션의 시스템 메모리 역할을 합니다.

• 시나리오 1: 단일 검색창 및 지속적인 대화: 검색 인터페이스에 기본 검색창이 하나만 있거나 지속적인 대화창이 있는 경우 최종 사용자가 관련이 없어 보이는 새로운 질문을 입력하더라도 conversationId가 재설정되지 않습니다. 시스템은 기존 대화 기록 (conversationId에 연결됨)을 사용하여 상황에 맞는 대답을 제공합니다.
• 시나리오 2: 별도의 대화 창과 질문 창: 검색 인터페이스에서 별도의 대화형 채팅 창과 별도의 표준 검색 질문 입력란 (예: 사이트 전체 검색창)을 제공하는 경우 표준 검색창에 새 질문을 입력하면 관련 없는 새 검색을 시작하려는 의도가 암시적으로 전달되어 해당 특정 검색 작업에 대해 conversationId이 재설정될 수 있습니다. 하지만 전용 대화창 내에서는 연속성을 위해 항상 conversationId이 유지되어야 합니다.

궁극적으로 conversationId를 재사용할지 아니면 재설정할지는 고객의 대화형 환경을 최적화하기 위한 디자인 선택입니다.

HTTP 메서드 및 엔드포인트 (초기 쿼리와 동일)

POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
    

대화형 API 요청:

후속 질문

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}
  

대화형 API 응답:

후속 응답

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}
  

최종 사용자가 계속 질문을 받는 경우의 예:

• 사용자 질문: 파티 계획을 도와줘.
• 시스템 답변: 어떤 파티를 계획 중이신가요?
• 사용자 대답: 생일 파티

소매업체가 대답으로 수행할 작업

필드를 렌더링하는 방식은 초기 응답과 비슷하지만 계속되는 대화를 반영하는 변경사항에 유의하세요.

• refined_search: 이 필드에는 최종 사용자의 최신 입력을 통합한 업데이트된 질문이 포함됩니다. 현재 쿼리에 맞게 클라이언트 콘솔을 업데이트해야 합니다 (예: 사용자에게 표시되는 쿼리가 '장식'에서 '생일 파티 장식' 또는 '생일 파티 용품'으로 변경됨). refined_search 쿼리는 핵심 검색 API (SearchService.Search) 호출에 사용하거나 최종 사용자에게 추천으로 표시할 수도 있습니다.
• conversational_text_response: 최신 턴과 관련된 새로운 AI 생성 텍스트 응답을 표시합니다.
• followup_question: 추가 개선을 위해 대화를 계속해야 하는 경우 새 followup_question이 제공됩니다.

상거래를 위한 Vertex AI Search에 전송할 이벤트

이벤트 태그는 검색어를 대화형 상호작용에 정확하게 귀속시키고 커머스용 Vertex AI Search의 분석 기능을 사용하는 데 중요합니다.

이벤트 태그 지정 프로세스에는 두 가지 단계가 있습니다.

1. conversation_id 가져오기 conversationalSearch API 호출을 하면 ConversationalSearchResponse.conversation_id가 반환됩니다.

2. 사용자 이벤트에 태그 지정 대화형 대답이 검색어로 이어지는 경우(예: refined_search 추천 표시) 또는 시스템에서 구체화된 질문을 기반으로 검색을 자동으로 실행하는 경우 후속 검색 사용자 이벤트(UserEvent)에 ConversationalSearchResponse에서 수신한 것과 동일한 onversation_id를 태그해야 합니다.

UserEvent.conversation_id에 올바르게 태그를 지정하면 애널리틱스에서 검색어를 이전 대화형 상호작용에 정확하게 귀속시켜 최종 사용자 행동과 전환 경로에 대한 유용한 정보를 제공할 수 있습니다.

대화형 제품 필터링과 에이전트 통합

이 가이드에서는 Conversational API와 대화형 제품 필터링을 모두 통합하여 AI 기반 쇼핑 경험을 제공하는 방법을 설명합니다. conversationalFilteringSpec.mode이 ENABLED로 설정되면 시스템이 개방형 대화형 상호작용과 가이드 제품 필터링 간에 직접 전환하여 매우 세련된 사용자 여정을 제공할 수 있습니다.

상호작용 이해하기

대화형 상거래 에이전트와 대화형 제품 필터링이 모두 사용 설정되면 시스템에서 각 기능의 장점을 활용합니다. 대화형 상거래 에이전트는 광범위한 문의를 처리하고, AI 생성 응답을 제공하고, 초기 인텐트를 개선합니다. 반면 대화형 제품 필터링은 간소화된 칩 또는 타일 기반 상호작용 모델을 사용하여 사용자가 특정 제품 속성을 선택하도록 안내합니다.

이 두 모드 간의 상호작용 및 잠재적 전환은 대화형 상거래 API의 분류가 제품 중심 검색(특히 SIMPLE_PRODUCT_SEARCH)으로 이어질 때 발생합니다. 이때 API는 직접 검색어를 제공하거나, 사용자의 의도를 더 구체화할 수 있는 경우 대화형 제품 필터링을 통해 안내 필터링 흐름을 트리거합니다.

이 통합의 핵심 원칙은 모든 자유 형식 텍스트 입력은 대화형 상거래 API에서 처리하고, 칩으로 표시되는 추천 답변 클릭은 대화형 제품 필터링에서 처리한다는 것입니다.

사용자 쿼리 보내기

사용자 입력 예시: 파티 계획을 도와줘

대화형 상거래 에이전트와 대화형 제품 필터링을 모두 사용 설정하려면 ConversationalSearchRequest에 다음 구성이 포함되어 있는지 확인하세요.

Conversational Commerce API 요청 - 초기 질문

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

주요 구성은 다음과 같습니다.

• Conversational_filtering_mode: ENABLED: conversationalFilteringSpec에서 이 필드를 ENABLED로 설정하면 시스템에서 대화형 제품 필터링을 처리할 수 있음을 API에 알릴 수 있으므로 API에서 관련 필터링 관련 응답을 제공할 수 있습니다.

초기 응답: 의도 개선

userQueryTypes 필드는 사용자의 의도를 이해하는 데 여전히 중요합니다. 파티 계획을 도와줘와 같은 초기 광범위한 질문의 경우 더 구체적인 제품 검색이 즉시 명확하지 않으면 API가 INTENT_REFINEMENT로 분류할 가능성이 높습니다.

Google의 응답

Conversational Commerce API 응답 - 초기 질문

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

작업

1. conversationalTextResponse를 표시합니다.
2. 장식, 간식과 같은 클릭 가능한 칩으로 refinedSearch 추천을 표시합니다. 또는 refined_search 질문을 사용하여 Commerce Search API를 병렬로 호출하여 대화형 교환과 함께 장식, 간식과 같은 관련 제품 결과를 캐러셀로 표시할 수 있습니다.
3. followupQuestion 표시: 어떤 파티를 계획하고 계신가요?
4. 자유 형식 사용자 입력으로 대화를 진행할 수 있습니다.

이벤트 태그 지정 및 분석

최초 대화형 상호작용에 대한 정확한 분석 및 기여 분석을 보장하려면 다음 단계를 따르세요.

• conversation_id 가져오기 ConversationalSearchResponse에서 conversation_id를 캡처합니다. 이 ID는 모든 후속 작업을 이 특정 대화 세션에 연결하는 데 중요합니다.
• 사용자 이벤트에 태그 지정 대화형 응답이 검색어로 이어지는 경우(예: 시스템이 refined_search 질문에 따라 자동으로 검색을 실행하는 경우) 또는 사용자가 refined_search 추천을 클릭하는 경우 후속 검색 사용자 이벤트(UserEvent)에 동일한 conversation_id를 태그해야 합니다.

후속 질문

사용자가 followupQuestion에 응답하면 대화가 구체화됩니다.

사용자 입력 예: 생일 파티

의도 개선 | 코드 스니펫

Conversational Commerce API 요청 - 후속 질문

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Conversational Commerce API 응답 - 후속 질문

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

작업

1. 초기 응답과 마찬가지로 새 conversationalTextResponse, refinedSearch 제안, followupQuestion로 웹 인터페이스를 업데이트합니다.
2. 대화 흐름을 계속하여 자세한 내용을 묻습니다.

이벤트 태그 지정 및 분석

사용자가 대화를 계속하는 경우:

• conversation_id 가져오기 이전 ConversationalSearchResponse의 conversation_id가 현재 ConversationalSearchRequest에 전달되는지 확인합니다.
• 사용자 이벤트에 태그 지정 대화형 응답으로 인해 사용자가 refined_search 추천을 클릭하거나 시스템에서 병렬 검색 호출을 하는 등 새로운 검색어가 발생하는 경우 후속 검색 사용자 이벤트 (UserEvent)에 동일한 conversation_id를 태그합니다. 이를 통해 멀티턴 대화 여정을 추적할 수 있습니다.

대화형 제품 필터링으로 전환

대화가 더 구체화되면 시스템에서 인텐트를 SIMPLE_PRODUCT_SEARCH로 분류하고 적절한 경우 대화형 제품 필터링을 트리거할 수 있습니다.

사용자 입력 예: 공주 테마

Conversational Commerce API 요청 - 후속 질문

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

핵심 제품 검색의 가능한 결과

쿼리가 SIMPLE_PRODUCT_SEARCH로 분류되면 대화형 제품 필터링이 트리거되는지에 따라 두 가지 API 응답이 가능합니다. 주요 차이점은 conversationalFilteringResult 필드의 존재 여부와 콘텐츠에 있습니다.

결과 1: 필터링이 트리거됨

이 문제는 제품 속성으로 더 구체화할 수 있을 만큼 쿼리가 핵심적인 경우에 발생합니다. 응답에는 웹 인터페이스에서 우선순위를 지정해야 하는 conversationalFilteringResult가 포함됩니다.

대화형 상거래 API 응답 - 제품 필터링으로 전환:

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

작업

이제 쿼리가 SIMPLE_PRODUCT_SEARCH로 분류되었습니다. 이 경우 대화형 제품 필터링이 트리거됩니다. 하지만 대화형 제품 필터링이 트리거되지 않을 수도 있습니다.

• 대화형 제품 필터링 웹 인터페이스 우선순위 지정:conversationalFilteringResult가 채워지면 제품 필터링 모드로 전환되었음을 나타냅니다. 웹 인터페이스에서는 사용자 인터페이스에 어떤 종류의 공주 장식을 찾고 계신가요?와 같이 표시되는 followupQuestion와 풍선, 스트리머, 식탁보와 같은 클릭 가능한 버튼인 suggestedAnswers를 강조해야 합니다.
• 제품 결과 표시: refined_search.query (공주 생일 장식)을 사용하여 Retail Search API를 즉시 호출하여 필터링 옵션과 함께 초기 제품 결과를 표시합니다.
• 권장 사용자 환경 사례: 전체 환경에 대해 지속적인 단일 자유 형식 텍스트 입력란이 있어야 합니다. 이 표시줄은 대화형 제품 필터링 흐름을 포함하여 항상 활성 상태로 유지됩니다. conversationalFilteringResult가 활성 상태이고 추천 답변이 클릭 가능한 칩으로 표시되면 사용자에게 다음과 같은 두 가지 명확한 옵션이 제공됩니다.
• 추천 답변을 클릭하여 필터링 흐름을 계속합니다.
• 활성 텍스트 표시줄에 새 질문을 입력하여 새 대화 턴을 시작합니다. 이 새로운 입력은 항상 Conversational Commerce API에 대한 새로운 호출을 트리거하여 현재 필터링 흐름을 효과적으로 종료합니다.

참고: 이 디자인 선택은 자유 형식 텍스트 입력은 Conversational Commerce API에서 처리하고 추천 답변 클릭은 대화형 제품 필터링에서 처리한다는 핵심 원칙과 일치합니다.

결과 2: 필터링이 트리거되지 않음

질문이 이미 충분히 구체적이거나 추가 필터링에 적합하지 않은 경우 대답에 conversationalFilteringResult 필드가 포함되지 않습니다. 이 경우 표준 검색을 진행해야 합니다.

작업

• 상호작용을 대화 흐름의 끝으로 처리하고 refined_search 쿼리를 사용하여 Retail Search API를 호출하고 표준 제품 결과 페이지를 표시합니다.

이벤트 태그 지정 및 분석

대화가 제품 필터링으로 전환되면 다음이 적용됩니다.

• conversation_id 가져오기 동일한 conversation_id를 계속 사용합니다.
• 사용자 이벤트에 태그 지정 전환으로 인해 즉시 검색이 이루어지는 경우 해당 UserEvent에 conversation_id 태그를 지정합니다. 중요한 점은 사용자가 suggestedAnswers와 상호작용할 때(예: 최종 사용자가 풍선을 클릭할 때) 이 작업은 동일한 conversation_id로 태그된 UserEvent(예: filter 이벤트 또는 새 search 이벤트)도 트리거해야 한다는 것입니다. 이를 통해 대화 흐름 내에서 필터링 작업의 기여도를 파악할 수 있습니다.

대화형 제품 필터링 계속하기

사용자가 suggestedAnswer를 선택하면 새 ConversationalSearchRequest를 전송합니다.

사용자 입력 예 (추천 답변 클릭): 풍선

간단한 제품 검색 | 코드 스니펫

대화형 상거래 API 요청 - 필터링 계속

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Conversational Commerce API 응답 - 계속 필터링

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

작업

API는 conversationalFilteringResult 필드 없이 SIMPLE_PRODUCT_SEARCH 쿼리로 응답하여 안내 필터링 흐름이 종료되었음을 나타냅니다.

• 최종 refinedSearch 쿼리(공주 생일 풍선)를 사용하여 Retail Search API를 직접 호출합니다.
• 사용자에게 최종 제품 결과를 표시합니다. 이 시점에서 대화가 종료되거나 사용자가 새로운 질문을 입력하여 새로운 차례를 시작할 수 있습니다.

이벤트 태그 지정 및 분석

제품 필터링 프로세스의 각 단계에서 다음을 수행합니다.

• conversation_id 가져오기 필터링 세션 내의 모든 요청에 항상 동일한 conversation_id를 사용합니다.
• 사용자 이벤트에 태그 지정 클릭과 같은 suggestedAnswer와의 각 사용자 상호작용은 새 쿼리가 형성되는 경우 filter 이벤트 또는 새 search 이벤트와 같은 관련 UserEvent을 트리거해야 합니다. 필터링 여정과 전환에 미치는 영향을 정확하게 추적하려면 이 UserEvent에 conversation_id 태그를 지정해야 합니다.

참조 아키텍처

이는 Google Cloud의 상거래를 위한 Vertex AI Search 참조 아키텍처 설계입니다. 이 참조 아키텍처는 대화형 상거래 에이전트의 데이터 및 서비스 흐름을 보여줍니다. 이 다이어그램은 사용자 이벤트, 제품 카탈로그 데이터, 운영 로그가 생성형 AI 색인 및 Retail 어댑터 서비스로 처리, 변환, 통합되어 검색 작업을 처리하고 사용자 의도를 충족하여 검색 결과를 반환하는 방법을 보여줍니다. 이 아키텍처는 다양한 프로젝트를 연결하여 포괄적인 AI 기반 상거래 검색 기능을 지원합니다.

다음 단계

추가 지원 리소스는 대화형 기능에 관한 질문의 답변을 참고하세요.