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

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

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

설정

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

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

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

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

최종 사용자가 보낸 질문

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

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

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

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

엔드포인트 1: Conversational API 요청

  • 사용자의 입력을 query로 설정하여 Conversational Commerce agent request를 만들어야 합니다.
  • 요청은 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 요청

UI에 검색 결과를 표시하는 기본 방법에는 두 가지가 있습니다.

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

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

  • 옵션 2: 대화형 출력에 따라 검색 결과 표시하기

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

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

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: 이 필드는 사용자의 의도 분류를 제공합니다. 이러한 유형에 따른 자세한 작업은 [질문 유형 및 소매업체 작업 이해하기](#step-2c)를 참고하세요.
  • 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까지 로드 표시기를 표시하는 등 UI 피드백에 사용할 수 있습니다. 자세한 내용은 2b단계. 스트리밍 API 이해하기

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

카테고리 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 또는 최종 사용자가 제공한 원래 검색어를 유연하게 사용할 수 있습니다. UI 및 검색 결과 표시 전략에 가장 적합한 옵션을 선택하세요.
    • 사용자 환경 옵션: SIMPLE_PRODUCT_SEARCH 질문의 경우 대화를 종료할 필요가 없습니다. 사용자는 후속 요청에서 conversation_id를 전달하여 대화를 계속할 수 있습니다.
      • 옵션 A: 대화형 UI 종료: 많은 소매업체는 SIMPLE_PRODUCT_SEARCH가 감지되면 사용자를 표준 검색 결과 페이지로 전환하여 채팅 창을 효과적으로 닫습니다. 이 시나리오에서 최종 사용자가 이전 conversation_id 없이 표준 검색창에 새 검색어를 입력하면 새롭고 별도의 대화로 처리되고 새 conversation_id가 발급됩니다.
      • 옵션 B: 대화형 UI 계속: 소매업체는 채팅 창을 열어 둘 수 있습니다. 이렇게 하면 사용자가 대화 모드로 되돌아갈 수 있습니다. 옵션 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 (UI에 적합한 숫자에 따라 1~3) refinedSearch 질문을 사용자에게 표시합니다.
  • 메커니즘: 이러한 추천 검색어는 백그라운드에서 또는 사용자 상호작용 시 핵심 검색 API (SearchService.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 요청에서 conversationId를 생략합니다.
    • 새 대화를 시작해야 하는 경우: 클라이언트는 다음과 같은 여러 일반적인 사용자 환경 시나리오에서 새 대화를 시작하여 API 응답에서 새로운 conversationId를 가져오려고 합니다.
      • 새 탭 또는 세션: 고객이 새 브라우저 탭에서 사이트를 열거나 완전히 새로운 세션을 시작하는 경우입니다.
      • 새 원래 질문: 일부 UX 디자인에서는 고객이 관련 없는 새 질문을 입력하는 경우 가장 관련성 높은 컨텍스트를 보장하기 위해 대화 흐름을 다시 시작할 수 있습니다.
      • 대화 다시 시작 버튼: UI에 명시적인 '새 채팅 시작' 또는 '대화 재설정' 버튼이 제공되는 경우 이 버튼을 클릭하면 새로운 대화 세션이 트리거됩니다.
    • 대화형 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을 포함해야 합니다.

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

추가 고려사항 및 권장사항

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

  • 방문자 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 옵션을 직관적으로 명확하게 표시하도록 UI를 디자인합니다.

다음 단계

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