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

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

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

설정

대화형 API는 대화형 상거래 에이전트 기능을 지원합니다.

• gRPC: conversationalSearchService
• REST: conversationalSearch

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

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

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

최종 사용자가 보낸 질문

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

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

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

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

엔드포인트 1: Conversational API 요청

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

HTTP 메서드 및 엔드포인트

  POST https://retail.googleapis.com/v2alpha/{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: 대화형 출력을 기반으로 검색 결과 표시

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

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

HTTP 메서드 및 엔드포인트

    POST https://retail.googleapis.com/v2beta/{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 이해

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

대답의 첫 번째 청크에는 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 자연어 응답을 의미합니다.

대화형 상거래 에이전트는 검색어 카테고리를 사용하여 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 검색을 구성하는 방법은 다음과 같습니다.

대화형 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이 포함되어야 합니다.

테이블 보기

세션 처리	설명	Conversational 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/v2alpha/{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에서 수신한 동일한 conversation_id를 태그해야 합니다.

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

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

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

상호작용 이해하기

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

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

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

사용자 쿼리 보내기

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

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

대화형 상거래 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에 응답하면 대화가 구체화됩니다.

사용자 입력 예: 생일 파티

의도 개선 | 코드 스니펫

대화형 상거래 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"
  }
}

대화형 상거래 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로 분류하고 적절한 경우 대화형 제품 필터링을 트리거할 수 있습니다.

사용자 입력 예: 공주 테마

대화형 상거래 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로 태그된 filter 이벤트 또는 새 search 이벤트와 같은 UserEvent도 트리거해야 한다는 것입니다. 이를 통해 대화 흐름 내에서 필터링 작업의 기여도를 파악할 수 있습니다.

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

사용자가 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는 SIMPLE_PRODUCT_SEARCH 쿼리로 응답하지만 conversationalFilteringResult 필드는 포함하지 않아 안내 필터링 흐름이 종료되었음을 나타냅니다.

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

이벤트 태그 지정 및 분석

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

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

사용자 인터페이스 권장사항 및 디자인 선택

대화형 상거래 에이전트와 대화형 제품 필터링 간의 상호작용은 상당한 유연성을 제공합니다. 원활하고 직관적인 환경을 만들기 위한 주요 UX 고려사항은 다음과 같습니다.

• 단일 입력창: 전체 환경에 자유 텍스트 입력창이 하나만 있어야 합니다. 대화형 제품 필터링을 위한 별도의 전용 입력창은 없습니다. 이렇게 하면 사용자 인터페이스가 간소화되고 상호작용이 일관되게 유지됩니다.
• 원활한 전환: 대화형 응답, 추천 질문, 필터링 옵션 간 전환이 자연스럽고 직관적으로 느껴지도록 웹 인터페이스를 설계합니다.
• 명확한 안내: 일반적인 입력 대신 추천 답변에 대해 명확한 버튼 스타일과 같은 시각적 단서를 사용하고 각 단계에서 상호작용하는 방법을 안내하는 명확한 안내를 사용합니다.
• 균형 잡힌 제어: 사용자는 항상 대화의 방향을 제어할 수 있어야 합니다.
• 필터링과 자유 형식의 차이: 단일 자유 텍스트 입력 표시줄은 항상 활성 상태로 유지됩니다. 이를 통해 사용자는 검색을 계속 구체화하기 위해 추천 답변을 클릭하거나 텍스트 표시줄에 새 질문을 입력하여 새로운 대화 턴을 시작할 수 있습니다. 이 디자인을 사용하면 필터링 흐름 중에도 사용자의 요구사항이 변경될 경우 다른 주제로 전환할 수 있습니다.
• 재설정 옵션: 사용자가 검색 또는 필터링 프로세스를 다시 시작할 수 있도록 명확한 새 대화 시작 또는 필터 재설정 옵션을 제공합니다.
• 시각적 지속성: 제품 필터링으로 전환할 때도 채팅 창 내에서 이전 질문과 답변을 표시하는 등 대화 기록을 유지하면 맥락과 사용자 환경을 개선할 수 있습니다.

추가 고려사항 및 권장사항

대화형 상거래 에이전트 인터페이스를 구현할 때는 다음과 같은 추가 고려사항과 권장사항을 고려해야 합니다.

• 방문자 ID 일관성: 특정 최종 사용자의 각 요청과 함께 고유한 visitor_id가 일관되게 전송되도록 지원합니다. 이는 정확한 맞춤설정과 모델 학습에 매우 중요합니다. 이 식별자는 세션과 로그인 또는 로그아웃 상태에서 최종 사용자에게 일관되게 유지되는 것이 좋습니다.
• 브랜치 관리: default_branch이 일반적이지만 제품 카탈로그가 여러 브랜치로 구성된 경우 올바른 브랜치 ID를 사용해야 합니다.
• 검색 API 상호작용: SIMPLE_PRODUCT_SEARCH 및 refined_search이 제공되는 모든 경우 실제 제품 목록을 가져오려면 refined_search 필드의 query 또는 원래 쿼리를 사용하여 핵심 검색 API (SearchService.Search)를 별도로 호출해야 합니다. Conversational API는 제품 결과를 직접 반환하기보다는 대화형 환경과 사용자 의도 이해에 주로 중점을 둡니다.
• 사용자 인터페이스 디자인: conversational_text_response, followup_question, refined_search 옵션을 직관적인 방식으로 명확하게 표시하여 사용자를 안내하도록 웹 인터페이스를 디자인합니다.

다음 단계

추가 지원 리소스는 대화형 기능 FAQ를 참고하세요.