Partilhar via

Biblioteca de cliente do Azure AI Search para JavaScript - versão 12.2.0

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 generativos que combinam grandes modelos de linguagem com dados corporativos.

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

  • Consolide vários tipos de conteúdo em um único índice pesquisável. Para preencher um índice, você pode enviar por push documentos JSON que contêm seu conteúdo ou, se seus dados já estiverem no Azure, criar um indexador para receber dados automaticamente.
  • Anexe conjuntos de habilidades a um indexador para criar conteúdo pesquisável a partir de imagens e documentos não estruturados. Um conjunto de habilidades aproveita as APIs dos Serviços de IA do Azure para OCR interno, reconhecimento de entidade, extração de frases-chave, deteçã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 seu conteúdo durante a ingestão de dados.
  • Em um aplicativo cliente de pesquisa, implemente a lógica de consulta e experiências do usuário semelhantes aos mecanismos de pesquisa comerciais da Web e aplicativos no estilo de bate-papo.

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

  • Envie consultas usando vetor, palavra-chave e formulários de consulta híbridos.
  • Implemente consultas filtradas para metadados, pesquisa geoespacial, navegação facetada ou para restringir resultados com base em critérios de filtro.
  • Crie e gerencie índices de pesquisa.
  • Carregue e atualize documentos no índice de pesquisa.
  • Crie e gerencie indexadores que extraem 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 avançada de texto ou conteúdo multilíngue.
  • Otimize os resultados por meio de classificação semântica e perfis de pontuação para levar em conta a lógica de negócios ou a atualização.

Ligações principais:

Primeiros passos

Instalar o pacote @azure/search-documents

npm install @azure/search-documents

Ambientes atualmente suportados

Consulte a nossa política de suporte para obter mais detalhes.

Pré-requisitos

Para criar um novo serviço de pesquisa, você pode usar o portal do Azure, o Azure PowerShell ou a CLI do Azure. Aqui está 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 a escolha de um nível de preços 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 para gerenciar índices ou SearchIndexerClient para 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 suportadas 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 da API do serviço de pesquisa:

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

Há dois tipos de chaves usadas para acessar seu serviço de pesquisa: admin(leitura-gravação) e query(somente leitura). Restringir o acesso e as operações em aplicativos cliente é essencial para proteger os ativos de pesquisa em seu serviço. Sempre use uma chave de consulta em vez de uma chave de administrador para qualquer consulta originada de um aplicativo cliente.

Observação: o trecho de exemplo da CLI do Azure acima recupera uma chave de administrador para que seja mais fácil começar a explorar APIs, mas deve ser gerenciado com cuidado.

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

import {
  SearchClient,
  AzureKeyCredential,
  SearchIndexClient,
  SearchIndexerClient,
} from "@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 autenticar em uma nuvem nacional, você precisará fazer as seguintes adições à configuração do seu cliente:

  • Definir a Audience entrada SearchClientOptions
import {
  SearchClient,
  AzureKeyCredential,
  KnownSearchAudience,
  SearchIndexClient,
  SearchIndexerClient,
} from "@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,
});

Conceitos-chave

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

Nota: Esses clientes não podem funcionar no navegador porque as APIs chamadas não têm suporte para CORS (Cross-Origin Resource Sharing).

Conceitos específicos do TypeScript/JavaScript

Documentação

Um item armazenado dentro de um índice de pesquisa. A forma deste documento é descrita no índice usando a fields propriedade. Cada SearchField um tem um nome, um tipo de dados e metadados adicionais, como se é pesquisável ou filtrável.

Paginação

Normalmente, você só desejará mostrar um subconjunto de resultados de pesquisa para um usuário de cada vez. 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 suportados em um índice são mapeados para tipos JSON em solicitações/respostas de API. A biblioteca de cliente JS mantém estes basicamente os mesmos, com algumas exceções:

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

Nota: 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 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 o básico - confira nossos exemplos para muito mais.

Criar um índice

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

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

const result = await indexClient.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(`Index created with name ${result.name}`);

Recuperar um documento específico de um índice

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

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

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

const result = await searchClient.getDocument("1234");

Adicionar documentos a um índice

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

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

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

const uploadResult = await searchClient.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}`);
}

Realizar 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:

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

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

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

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

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

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

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

Consultando com TypeScript

Em TypeScript, SearchClient usa um parâmetro genérico que é a forma de modelo de seus documentos de índice. Isso permite que você execute uma pesquisa fortemente tipada dos campos retornados nos resultados. TypeScript também é capaz de verificar os 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>;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | null;
  }>;
}

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

const searchResults = await searchClient.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);
}

Consultando com filtros OData

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

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

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

const baseRateMax = 200;
const ratingMin = 4;
const searchResults = await searchClient.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);
}

Consultando com vetores

As incorporações de texto podem ser consultadas usando o vector parâmetro de pesquisa. Consulte Consultar vetores e Filtrar consultas vetoriais para obter mais informações.

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

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

const queryVector: number[] = [
  // Embedding of the query "What are the most luxurious hotels?"
];
const searchResults = await searchClient.search("*", {
  vectorSearchOptions: {
    queries: [
      {
        kind: "vector",
        vector: queryVector,
        fields: ["descriptionVector"],
        kNearestNeighborsCount: 3,
      },
    ],
  },
});
for await (const result of searchResults.results) {
  // These results are the nearest neighbors to the query vector
  console.log(result);
}

Consultando com facetas

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

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

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

const searchResults = await searchClient.search("WiFi", {
  facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
});
console.log(searchResults.facets);

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

Solução de problemas

Registo

Habilitar o registro em 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 registro em log pode ser habilitado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

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

Próximos passos

Contribuição

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

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

Este projeto adotou o Código de Conduta Open Source da Microsoft. Para obter mais informações, consulte o de perguntas frequentes sobre o Código de Conduta ou entre em contato com para obter perguntas ou comentários adicionais.

  • Last updated on