Extensão da Vertex AI para Pesquisa

Este documento mostra como registrar e usar a extensão da Vertex AI para Pesquisa fornecida pelo Google no console do Google Cloud e na API Vertex AI. Essa extensão permite acessar e pesquisar corpus de sites e dados não estruturados para fornecer respostas relevantes a perguntas de linguagem natural, como:

  • "Como as ameaças competitivas para a empresa mudaram do primeiro trimestre do ano passado para o primeiro trimestre deste ano?"
  • "Quais partes da empresa estão crescendo mais rápido? Com que rapidez?"

A extensão Vertex AI para Pesquisa usa a Vertex AI para Pesquisa para recuperar resultados significativos do seu repositório de dados. A extensão Vertex AI para Pesquisa é definida em um arquivo vertex_ai_search.yaml da especificação OpenAPI.

Para usar a extensão da Vertex AI para Pesquisa, você precisa Criar um repositório de dados na região global com um escopo de pesquisa especificado. Para melhores resultados de pesquisa, ative a indexação avançada para dados de sites e a edição Enterprise para dados não estruturados. Consulte Sobre recursos avançados para mais informações.

openapi: "3.0.0"
info:
  title: Vertex AI Search
  version: v1alpha
  description: >
    Performs search on user ingested data including website and unstructured data type.

    This extension is used when user wants to search or retrieve meaningful results from their ingested data in the Vertex AI Search service.

    Supported AuthTypes:
    - GOOGLE_SERVICE_ACCOUNT_AUTH: (only supports using Vertex AI Extension Service Agent).
paths:
  /search:
    get:
      operationId: search
      description: Retrieves the results from user's query by searching in the data store.
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: User natural language instructions for search.
        required: true
      responses:
        default:
          description: Search execution result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResult"

components:
  schemas:
    SearchResult:
      description: Top results from search response.
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: Retrieved document title.
              display_link:
                type: string
                description: Retrieved document link to display.
              link:
                type: string
                description: Retrieved document link.
              extractive_segments:
                type: array
                description: Extractive segments from the retrieved file.
                items:
                  type: string
              extractive_answers:
                type: array
                description: Extractive answers from the retrieved file. These are generated from the extractive segments.
                items:
                  type: string

    

Para saber mais sobre as extensões do Google com tutoriais completos, consulte os seguintes notebooks do Jupyter:

  • Fluxo de trabalho de analistas de negócios com extensões da Vertex AI: use a extensão Code Interpreter e a extensão Vertex AI para Pesquisa para concluir um relatório de pesquisa de oportunidades de investimento em habitação para as partes interessadas de negócios.
    Colab | GitHub | Vertex AI Workbench
  • Fluxo de trabalho de análise de avaliações de jogos com as extensões da Vertex AI: use a extensão do Code Interpreter para analisar as avaliações de jogos do Steam. Use a extensão Vertex AI para Pesquisa para resumir avaliações de jogos em sites. Use a extensão Intérprete de código para criar um relatório com todos os recursos gerados.
    Colab | GitHub | Vertex AI Workbench

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Enable the API

Registrar e executar a extensão da Vertex AI para Pesquisa

As seções a seguir mostram como registrar a extensão da Vertex AI para Pesquisa usando o console do Google Cloud e a API Vertex AI. Depois de registrar a extensão, execute-a usando a API Vertex AI.

Console

Registrar a extensão

Siga as etapas abaixo para registrar a extensão da Vertex AI para Pesquisa usando o console do Google Cloud.

  1. No console do Google Cloud, acesse a página Extensões da Vertex AI.

    Acesse as extensões da Vertex AI

  2. Clique em Criar extensão.

  3. Na caixa de diálogo Criar uma nova extensão, preencha os seguintes campos:

    • Nome da extensão: insira um nome para a extensão, como "vertex_search_extension".
    • Descrição: (opcional) insira uma descrição da extensão, como "Uma extensão de pesquisa da Vertex AI".
    • Tipo de extensão: selecione Vertex AI search.
  4. Na seção Arquivo de especificação da OpenAPI exibida, verifique se os campos a seguir estão definidos corretamente:

    • Nome da API: vertex_ai_search.
    • Descrição de APIs: Performs search on user ingested data including website and unstructured data type...
    • Fonte: Cloud Storage.
    • Especificação da OpenAPI: vertex-extension-public/vertex_ai_search.yaml.
    • Autenticação: Google service account.
  5. Na seção Configurações do ambiente de execução, forneça um nome para a configuração de exibição. O nome da configuração de exibição é especificado em vertexAiSearchRuntimeConfig. Ele é formatado e concluído da seguinte maneira: projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG

    • Defina COLLECTION_NAME como default_collection.
    • Defina ENGINE como o ID do aplicativo que você recebeu ao criar o app de pesquisa. Para saber mais, consulte Criar um app de pesquisa para os dados de sites.
    • Defina SERVING_CONFIG como default_search.
  6. Clique em Criar extensão.

REST

Registrar a extensão

Envie uma solicitação da API Vertex AI extensions.import para registrar a extensão Vertex AI para Pesquisa.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud.
  • REGION: uma região do Compute Engine.
  • DISPLAY_NAME: a extensão nome mostrada aos usuários, como "my_search_extension".
  • DESCRIPTION: (opcional) a descrição da extensão que é exibida aos usuários, como "Uma extensão de pesquisa".
  • SERVICE_ACCOUNT: (opcional) a extensão Vertex AI para Pesquisa usa GOOGLE_SERVICE_ACCOUNT_AUTH como mostrado no corpo da solicitação de exemplo. Se você não especificar uma conta de serviço, a extensão vai usar a conta de serviço padrão do Agente de serviço de extensão da Vertex AI. Se você especificar uma conta de serviço diferente, conceda a permissão iam.serviceAccounts.getAccessToken à conta de serviço do Agente de serviço de extensão da Vertex AI na conta de serviço especificada.
  • SERVING_CONFIG_NAME: o nome da configuração de exibição é especificado em vertexAiSearchRuntimeConfig. Ele é formatado e concluído da seguinte maneira: projects/PROJECT_ID/locations/global/collections/COLLECTION_NAME/engines/ENGINE/servingConfigs/SERVING_CONFIG.
    • PROJECT_ID: o ID do projeto do Google Cloud.
    • Defina COLLECTION_NAME como default_collection.
    • ENGINE: o ID do aplicativo que você recebeu quando criou o app de pesquisa. Para saber mais, consulte Criar um app de pesquisa para os dados de sites.
    • Defina SERVING_CONFIG como default_search.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import

Corpo JSON da solicitação:

{
  "displayName":"DISPLAY_NAME",
  "description":"DESCRIPTION",
  "manifest":{
    "name":"vertex_ai_search_tool",
    "description":"A Vertex AI Search tool",
    "apiSpec":{
      "openApiGcsUri":"gs://vertex-extension-public/vertex_ai_search.yaml"
    },
    "authConfig":{
      "authType":"GOOGLE_SERVICE_ACCOUNT_AUTH",
      "googleServiceAccountConfig":{
        "serviceAccount":"SERVICE_ACCOUNT"
      }
    }
  }
  "runtimeConfig": {
     "vertexAiSearchRuntimeConfig": {
        "servingConfigName": "SERVING_CONFIG_NAME",
     }
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions:import" | Select-Object -Expand Content

Executar a extensão

É possível enviar uma operação execute à API Vertex AI para receber resultados significativos do repositório de dados.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud.
  • REGION: uma região do Compute Engine.
  • EXTENSION_ID: o ID da extensão da Vertex AI para Pesquisa listado nos Detalhes da extensão no console do Google Cloud.

Método HTTP e URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute

Corpo JSON da solicitação:

{
  "operation_id":"search",
  "operation_params":{
    "query":"Housing affordability since 2010",
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/extensions/EXTENSION_ID:execute" | Select-Object -Expand Content