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

Artigo
08/02/2024

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 cliente @azure/search-documents 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

versões LTS do Node.js
Versões mais recentes do Safari, Chrome, Microsoft Edge e Firefox.

Consulte o nosso de política de suporte para obter mais detalhes.

Pré-requisitos

Uma assinatura do Azure
Um serviço de Pesquisa

Para criar um novo serviço de pesquisa, você pode usar odo portal do Azure, do Azure PowerShell ou oda 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 escolher um de 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 de 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 de ponto de extremidade e uma chave de API do serviço de pesquisa no portal do Azure. Consulte a de documentação do para obter instruções sobre como obter uma chave 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: dede administrador (leitura-gravação) e de consulta (somente leitura) chaves. 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:

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 autenticar em um National Cloud, você precisará fazer as seguintes adições à configuração do seu cliente:

Defina 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 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 biblioteca de cliente @azure/search-documents expõe operações nesses recursos por meio de três tipos de cliente principais.

SearchClient ajuda com:
- Pesquisando seus documentos indexados usando consultas vetoriais , consultas de palavras-chave e consultas híbridas
- Filtros de consulta vetorial e filtros de consulta de texto
- de classificação semântica e perfis de pontuação para aumentar a relevância
- Preenchimento automático termos de pesquisa parcialmente digitados com base em documentos no índice
- Sugerindo o texto correspondente mais provável em documentos à medida que um usuário digita
- Adicionar, atualizar ou excluir documentos documentos de um índice
SearchIndexClient permite-lhe:
- Criar, excluir, atualizar ou configurar um índice de pesquisa
- Declare mapas de sinônimos personalizados para expandir ou reescrever consultas
SearchIndexerClient permite-lhe:
- Inicie indexadores para rastrear automaticamente fontes de dados
- Defina Skillsets alimentados por IA para transformar e enriquecer seus dados

Observação: Esses clientes não podem funcionar no navegador porque as APIs que ele chama 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 propriedade fields. Cada SearchField 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 a um usuário de uma só vez. Para dar suporte a isso, você pode usar os parâmetros top, skip e includeTotalCount 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 DateJS.
Edm.GeographyPoint é convertido em um tipo de GeographyPoint exportado pela biblioteca do cliente.
Valores especiais do tipo number (NaN, Infinity -Infinity) são serializados como cadeias de caracteres na API REST, mas são convertidos de volta para number pela biblioteca do cliente.

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 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 - por favor, confira nossos exemplos para muito mais.

Criação de um índice
Recuperar um documento específico do seu índice
Adicionar documentos ao seu índice
Realizar uma pesquisa em documentos

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 seu 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

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();

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:

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 sintaxe Lucene, especifique queryType a ser 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

No TypeScript, SearchClient usa um parâmetro genérico que é a forma do 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 parâmetro select.

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 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();

Consultando com filtros OData

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

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 incorporações de texto podem ser consultadas usando o parâmetro de pesquisa vector. Consulte Consultar vetores e Filtrar consultas vetoriais para obter mais informações.

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

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

async function main() {
  const queryVector = [...];
  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);
  }
}

main();

Facetas são usadas para ajudar um usuário do seu aplicativo a refinar uma pesquisa em dimensões pré-configuradas. de sintaxe de facetas fornece as opções para classificar e agrupar 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 recuperar resultados, uma propriedade facets estará disponível que indicará o número de resultados que caem em cada bucket de facetas. 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

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 Microsoft Open Source Code of Conduct. 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.

SDK do Microsoft Azure para JavaScript

Impressões

Partilhar via

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

Primeiros passos

Instalar o pacote `@azure/search-documents`

Ambientes atualmente suportados

Pré-requisitos

Autenticar o cliente

Obter uma chave de API

Autenticar em uma nuvem nacional

Conceitos-chave

Conceitos específicos do TypeScript/JavaScript

Documentação

Codificação de campo de documento

Exemplos

Criar um índice

Recuperar um documento específico de um índice

Adicionar documentos a um índice

Realizar uma pesquisa em documentos

Consultando com TypeScript

Consultando com filtros OData

Consultando com vetores

Consultando com facetas

Solução de problemas

Registo

Próximos passos

Contribuição

Recursos adicionais

Partilhar via

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

Primeiros passos

Instalar o pacote @azure/search-documents

Ambientes atualmente suportados

Pré-requisitos

Autenticar o cliente

Obter uma chave de API

Autenticar em uma nuvem nacional

Conceitos-chave

Conceitos específicos do TypeScript/JavaScript

Documentação

Paginação

Codificação de campo de documento

Exemplos

Criar um índice

Recuperar um documento específico de um índice

Adicionar documentos a um índice

Realizar uma pesquisa em documentos

Consultando com TypeScript

Consultando com filtros OData

Consultando com vetores

Consultando com facetas

Solução de problemas

Registo

Próximos passos

Contribuição

Projetos relacionados

Recursos adicionais

Instalar o pacote `@azure/search-documents`