Biblioteca de cliente da Pesquisa de IA do Azure para JavaScript – versão 12.0.0

  • Artigo

O Azure AI Search (anteriormente conhecido como "Azure Cognitive Search") é uma plataforma de obtenção de informações com tecnologia de IA que ajuda os programadores a criar experiências de pesquisa avançadas e aplicações de IA geradoras que combinam modelos de linguagem grandes com dados empresariais.

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

  • Consolidar tipos de conteúdo variados num único índice pesquisável. Para preencher um índice, pode emitir documentos JSON que contenham o seu conteúdo ou, se os seus dados já estiverem no Azure, crie um indexador para solicitar dados automaticamente.
  • Anexe conjuntos de competências a um indexador para criar conteúdos pesquisáveis a partir de imagens e documentos de texto grandes. Um conjunto de competências tira partido das APIs dos serviços de IA para OCR incorporado, reconhecimento de entidades, extração de expressões-chave, deteção de idiomas, tradução de texto e análise de sentimentos. Também pode adicionar competências personalizadas para integrar o processamento externo dos seus conteúdos durante a ingestão de dados.
  • Numa aplicação cliente de pesquisa, implemente a lógica de consulta e as experiências de utilizador semelhantes aos motores de busca web comerciais.

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

  • Submeta consultas com formulários de vetor, palavra-chave e consulta híbrida.
  • Implemente consultas filtradas para metadados, pesquisa geoespacial, navegação facetada ou para restringir resultados com base em critérios de filtro.
  • Criar e gerir índices de pesquisa.
  • Carregar e atualizar documentos no índice de pesquisa.
  • Crie e faça a gestão de indexadores que extraem dados do Azure para um índice.
  • Crie e faça a gestão de conjuntos de competências que adicionam o melhoramento de IA à ingestão de dados.
  • Crie e faça a gestão de analisadores para análise de texto avançada ou conteúdo multilinngue.
  • Otimize os resultados através de perfis de classificação para ter em conta a lógica de negócio ou a frescura.

Ligações principais:

Introdução

Instalar o pacote @azure/search-documents

npm install @azure/search-documents

Ambientes atualmente suportados

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

Pré-requisitos

Para criar um novo serviço de pesquisa, pode utilizar o portal do Azure, Azure PowerShell ou a CLI do Azure. Eis um exemplo que utiliza 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

Veja escolher um escalão 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, terá de criar uma instância da classe de cliente adequada: SearchClient para procurar documentos indexados, SearchIndexClient para gerir índices ou SearchIndexerClient para pesquisar origens de dados e carregar documentos de pesquisa para um índice.

Para instanciar um objeto de cliente, precisará de um ponto final e de funções do Azure ou de uma chave de API. 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ções pré-existentes.

Pode obter o ponto final 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.

Em alternativa, pode utilizar o seguinte comando da CLI do Azure para obter a chave de API do serviço de pesquisa:

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

Assim que tiver uma chave de api, pode utilizá-la da seguinte forma:

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 numa Cloud Nacional

Para se autenticar numa Cloud Nacional, terá de 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,
});

Conceitos-chave

Um Serviço de 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 não estiver familiarizado com a pesquisa, pode criar uma analogia muito aproximada entre índices e tabelas de bases de dados.) A @azure/search-documents biblioteca de cliente expõe operações nestes recursos através de três tipos de cliente principais.

Nota: estes clientes não podem funcionar no browser porque as APIs a que chama não têm suporte para a Partilha de Recursos Entre Origens (CORS).

Conceitos específicos de TypeScript/JavaScript

Documentos

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

Paginação

Normalmente, apenas pretende mostrar um subconjunto de resultados de pesquisa a um utilizador de uma só vez. Para o suportar, pode utilizar os topparâmetros e includeTotalCountskip para fornecer uma experiência paginada sobre os resultados da pesquisa.

Codificação de campos de documentos

Os tipos de dados suportados num índice são mapeados para tipos JSON em pedidos/respostas de API. A biblioteca de cliente JS mantém-nas maioritariamente iguais, com algumas exceções:

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

Nota: os tipos de dados são convertidos com base no valor e não no tipo de campo no esquema de índice. Isto significa que, se tiver uma cadeia data de ISO8601 (por exemplo, "2020-03-06T18:48:27.896Z") como o valor de um campo, será convertida numa Data, independentemente da forma como o armazenou no esquema.

Exemplos

Os exemplos seguintes demonstram as noções básicas: consulte os nossos exemplos para obter 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();

Obter um documento específico a partir de um índice

Um documento específico pode ser obtido pelo respetivo valor de 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();

Adicionar documentos a um índice

Pode carregar vários documentos para o í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();

Efetuar uma pesquisa em documentos

Para listar todos os resultados de uma consulta específica, pode utilizar search com uma cadeia de pesquisa que utilize 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 utiliza 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();

Consultar com TypeScript

Em TypeScript, SearchClient utiliza um parâmetro genérico que é a forma de modelo dos seus documentos de índice. Isto permite-lhe efetuar uma pesquisa de campos fortemente digitadas devolvida nos resultados. O TypeScript também pode verificar se existem campos devolvidos 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

A utilização do filter parâmetro de consulta permite-lhe consultar um índice com a sintaxe de uma expressão $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();

Consultar com vetores

As incorporações de texto podem ser consultadas com 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();

Consultar com facetas

As facetas são utilizadas para ajudar um utilizador da sua aplicação a refinar uma pesquisa ao longo de dimensões pré-configuradas. A sintaxe faceta fornece as opções para ordenar e criar registos de valores de facetas.

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 obter resultados, estará disponível uma facets propriedade que indicará o número de resultados que se enquadram em cada registo de facetas. Isto pode ser utilizado para impulsionar o refinamento (por exemplo, emitir uma pesquisa de seguimento que filtra por Rating ser maior ou igual a 3 e inferior a 4.)

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar registos, pode ver os documentos do pacote de @azure/logger.

Passos seguintes

Contribuir

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

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta do Microsoft Open Source. Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões