Biblioteca de clientes do Azure AI Search para JavaScript – versão 12.0.0

  • Artigo

O Azure AI Search (anteriormente conhecido como "Azure Cognitive Search") é uma plataforma de recuperação de informações alimentada por IA que ajuda os desenvolvedores a criar experiências de pesquisa avançadas e aplicativos de IA geradores que combinam modelos de linguagem grandes com dados corporativos.

O Azure AI Search é adequado para os seguintes cenários de aplicativo:

  • Consolide tipos de conteúdo variados em um único índice pesquisável. Para preencher um índice, você pode enviar por push documentos JSON que contenham seu conteúdo ou, se os dados já estiverem no Azure, criar um indexador para efetuar pull de dados automaticamente.
  • Anexe conjuntos de habilidades a um indexador para criar conteúdo pesquisável a partir de imagens e documentos de texto grande. Um conjunto de habilidades utiliza APIs de serviços de IA para OCR interno, reconhecimento de entidade, extração de frases-chave, detecção de idioma, tradução de texto e análise de sentimento. Você também pode adicionar habilidades personalizadas para integrar o processamento externo do conteúdo durante a ingestão de dados.
  • Em um aplicativo cliente de pesquisa, implemente a lógica de consulta e as experiências do usuário semelhantes aos mecanismos de pesquisa da Web comercial.

Use a @azure/search-documents biblioteca de clientes para:

  • Envie consultas usando formulários de consulta híbrida, palavra-chave e vetor.
  • Implemente consultas filtradas para metadados, pesquisa geoespacial, navegação facetada ou para restringir resultados com base em critérios de filtro.
  • Criar e gerenciar índices de pesquisa.
  • Carregue e atualize documentos no índice de pesquisa.
  • Crie e gerencie indexadores que efetuam pull de dados do Azure para um índice.
  • Crie e gerencie conjuntos de habilidades que adicionam enriquecimento de IA à ingestão de dados.
  • Crie e gerencie analisadores para análise de texto avançada ou conteúdo multilíngue.
  • Otimize os resultados por meio de perfis de pontuação para considerar a lógica de negócios ou a atualização.

Links principais:

Introdução

Instalar o pacote @azure/search-documents

npm install @azure/search-documents

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

Para criar um novo serviço de pesquisa, você pode usar o portal do Azure, Azure PowerShell ou a CLI do Azure. Veja um exemplo usando a CLI do Azure para criar uma instância gratuita para começar:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Consulte escolhendo um tipo de preço para obter mais informações sobre as opções disponíveis.

Autenticar o cliente

Para interagir com o serviço de pesquisa, você precisará criar uma instância da classe de cliente apropriada: SearchClient para pesquisar documentos indexados, SearchIndexClient gerenciar índices ou SearchIndexerClient rastrear fontes de dados e carregar documentos de pesquisa em um índice.

Para instanciar um objeto cliente, você precisará de um ponto de extremidade e funções do Azure ou uma chave de API. Você pode consultar a documentação para obter mais informações sobre abordagens de autenticação com suporte com o serviço de pesquisa.

Obter uma chave de API

Uma chave de API pode ser uma abordagem mais fácil de começar porque não requer atribuições de função pré-existentes.

Você pode obter o ponto de extremidade e uma chave de API do serviço de pesquisa no Portal do Azure. Consulte a documentação para obter instruções sobre como obter uma chave de API.

Como alternativa, você pode usar o seguinte comando da CLI do Azure para recuperar a chave de API do serviço de pesquisa:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

Depois de ter uma chave de api, você poderá usá-la da seguinte maneira:

const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

Autenticar em uma nuvem nacional

Para se autenticar em uma Nuvem Nacional, você precisará fazer as seguintes adições à configuração do cliente:

  • Definir o Audience em SearchClientOptions
const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
  KnownSearchAudience,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
  {
    audience: KnownSearchAudience.AzureChina,
  }
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

Principais conceitos

Um serviço Pesquisa de IA do Azure contém um ou mais índices que fornecem armazenamento persistente de dados pesquisáveis na forma de documentos JSON. (Se você for novo em pesquisa, poderá fazer uma analogia muito aproximada entre índices e tabelas de banco de dados.) A @azure/search-documents biblioteca de clientes expõe operações nesses recursos por meio de três tipos de cliente main.

Observação: esses clientes não podem funcionar no navegador porque as APIs que ele chama não têm suporte para CORS (Compartilhamento de Recursos entre Origens).

Conceitos específicos de TypeScript/JavaScript

Documentos

Um item armazenado dentro de um índice de pesquisa. A forma deste documento é descrita no índice usando Fields. Cada Campo tem um nome, um tipo de dados e metadados adicionais, como se fosse pesquisável ou filtreável.

Paginação

Normalmente, você só deseja mostrar um subconjunto de resultados de pesquisa para um usuário ao mesmo tempo. Para dar suporte a isso, você pode usar os topparâmetros e skipincludeTotalCount para fornecer uma experiência paginada sobre os resultados da pesquisa.

Codificação de campo de documento

Os tipos de dados com suporte em um índice são mapeados para tipos JSON em solicitações/respostas de API. A biblioteca de clientes JS mantém estes principalmente os mesmos, com algumas exceções:

  • Edm.DateTimeOffset é convertido em um JS Date.
  • Edm.GeographyPoint é convertido em um GeographyPoint tipo exportado pela biblioteca de clientes.
  • Os valores especiais do number tipo (NaN, Infinity, -Infinity) são serializados como cadeias de caracteres na API REST, mas são convertidos number novamente na biblioteca de clientes.

Observação: os tipos de dados são convertidos com base no valor, não no tipo de campo no esquema de índice. Isso significa que, se você tiver uma cadeia de caracteres de data ISO8601 (por exemplo, "2020-03-06T18:48:27.896Z") como o valor de um campo, ela será convertida em uma Data, independentemente de como você a armazenou em seu esquema.

Exemplos

Os exemplos a seguir demonstram as noções básicas : marcar nossos exemplos para muito mais.

Criar um índice

const { SearchIndexClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.createIndex({
    name: "example-index",
    fields: [
      {
        type: "Edm.String",
        name: "id",
        key: true,
      },
      {
        type: "Edm.Double",
        name: "awesomenessLevel",
        sortable: true,
        filterable: true,
        facetable: true,
      },
      {
        type: "Edm.String",
        name: "description",
        searchable: true,
      },
      {
        type: "Edm.ComplexType",
        name: "details",
        fields: [
          {
            type: "Collection(Edm.String)",
            name: "tags",
            searchable: true,
          },
        ],
      },
      {
        type: "Edm.Int32",
        name: "hiddenWeight",
        hidden: true,
      },
    ],
  });

  console.log(result);
}

main();

Recuperar um documento específico de um índice

Um documento específico pode ser recuperado pelo valor da chave primária:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.getDocument("1234");
  console.log(result);
}

main();

Adicionando documentos a um índice

Você pode carregar vários documentos no índice dentro de um lote:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const uploadResult = await client.uploadDocuments([
    // JSON objects matching the shape of the client's index
    {},
    {},
    {},
  ]);
  for (const result of uploadResult.results) {
    console.log(`Uploaded ${result.key}; succeeded? ${result.succeeded}`);
  }
}

main();

Executar uma pesquisa em documentos

Para listar todos os resultados de uma consulta específica, você pode usar search com uma cadeia de caracteres de pesquisa que usa sintaxe de consulta simples:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search("wifi -luxury");
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

Para uma pesquisa mais avançada que usa a sintaxe Lucene, especifique queryType como full:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search('Category:budget AND "recently renovated"^3', {
    queryType: "full",
    searchMode: "all",
  });
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

Consultando com TypeScript

Em TypeScript, SearchClient usa um parâmetro genérico que é a forma de modelo dos documentos de índice. Isso permite que você execute uma pesquisa fortemente tipada de campos retornados nos resultados. TypeScript também é capaz de marcar para campos retornados ao especificar um select parâmetro.

import { SearchClient, AzureKeyCredential, SelectFields } from "@azure/search-documents";

// An example schema for documents in the index
interface Hotel {
  hotelId?: string;
  hotelName?: string | null;
  description?: string | null;
  descriptionVector?: Array<number> | null;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | null;
  } | null>;
}

const client = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search("wifi -luxury", {
    // Only fields in Hotel can be added to this array.
    // TS will complain if one is misspelled.
    select: ["hotelId", "hotelName", "rooms/beds"],
  });

  // These are other ways to declare the correct type for `select`.
  const select = ["hotelId", "hotelName", "rooms/beds"] as const;
  // This declaration lets you opt out of narrowing the TypeScript type of your documents,
  // though the AI Search service will still only return these fields.
  const selectWide: SelectFields<Hotel>[] = ["hotelId", "hotelName", "rooms/beds"];
  // This is an invalid declaration. Passing this to `select` will result in a compiler error
  // unless you opt out of including the model in the client constructor.
  const selectInvalid = ["hotelId", "hotelName", "rooms/beds"];

  for await (const result of searchResults.results) {
    // result.document has hotelId, hotelName, and rating.
    // Trying to access result.document.description would emit a TS error.
    console.log(result.document.hotelName);
  }
}

main();

Consultar com filtros OData

O uso do filter parâmetro de consulta permite consultar um índice usando a sintaxe de uma expressão de $filter OData.

const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const baseRateMax = 200;
  const ratingMin = 4;
  const searchResults = await client.search("WiFi", {
    filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
    orderBy: ["Rating desc"],
    select: ["hotelId", "hotelName", "rating"],
  });
  for await (const result of searchResults.results) {
    // Each result will have "HotelId", "HotelName", and "Rating"
    // in addition to the standard search result property "score"
    console.log(result);
  }
}

main();

Consultando com vetores

As inserções de texto podem ser consultadas usando o vector parâmetro de pesquisa.

const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");

const searchClient = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const queryVector = [...]
  const searchResults = await searchClient.search("*", {
    vector: {
      fields: ["descriptionVector"],
      kNearestNeighborsCount: 3,
      value: queryVector,
    },
  });
  for await (const result of searchResults.results) {
    // These results are the nearest neighbors to the query vector
    console.log(result);
  }
}

main();

Consultando com facetas

As facetas são usadas para ajudar um usuário do aplicativo a refinar uma pesquisa em dimensões pré-configuradas. A sintaxe de faceta fornece as opções para classificar e valores de faceta de bucket.

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search("WiFi", {
    facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
  });
  console.log(searchResults.facets);
  // Output will look like:
  // {
  //   'rooms/baseRate': [
  //     { count: 16, value: 0 },
  //     { count: 17, value: 100 },
  //     { count: 17, value: 200 }
  //   ],
  //   category: [
  //     { count: 5, value: 'Budget' },
  //     { count: 5, value: 'Luxury' },
  //     { count: 5, value: 'Resort and Spa' }
  //   ]
  // }
}

main();

Ao recuperar resultados, uma facets propriedade estará disponível que indicará o número de resultados que se enquadram em cada bucket de faceta. Isso pode ser usado para impulsionar o refinamento (por exemplo, emitir uma pesquisa de acompanhamento que filtra o Rating sendo maior ou igual a 3 e menor que 4).)

Solução de problemas

Registro em log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as Perguntas frequentes sobre o Código de Conduta ou entre em contato opencode@microsoft.com com perguntas ou comentários adicionais.

Impressões