Клиентская библиотека службы "Поиск Azure AI" для JavaScript - версия 12.2.0

Поиск Azure AI (прежнее название — Azure Cognitive Search) — это платформа для извлечения информации на основе искусственного интеллекта, которая помогает разработчикам создавать широкие возможности поиска и приложения генеративного искусственного интеллекта, объединяющие большие языковые модели с корпоративными данными.

Служба поиска ИИ Azure хорошо подходит для следующих сценариев приложения:

Объединить различные типы контента в один индекс, доступный для поиска. Чтобы заполнить индекс, можно отправить документы JSON, содержащие содержимое, или если данные уже есть в Azure, создайте индексатор для автоматического извлечения данных.
Подключите наборы навыков к индексатору для создания содержимого, доступного для поиска, из изображений и неструктурированных документов. Набор навыков использует API из служб ИИ Azure для встроенного OCR, распознавания сущностей, извлечения ключевых фраз, обнаружения языка, перевода текста и анализа тональности. Вы также можете добавить пользовательские навыки для интеграции внешней обработки содержимого во время приема данных.
В клиентском приложении поиска реализуйте логику запросов и пользовательские возможности, аналогичные коммерческим поисковым системам и приложениям в стиле чата.

Используйте клиентскую библиотеку @azure/search-documents для:

Отправка запросов с помощью векторных, ключевых слов и гибридных форм запросов.
Реализуйте отфильтрованные запросы для метаданных, геопространственного поиска, фасетной навигации или узких результатов на основе критериев фильтра.
Создание индексов поиска и управление ими.
Отправка и обновление документов в индексе поиска.
Создайте индексаторы и управляйте ими, извлекающими данные из Azure в индекс.
Создание наборов навыков и управление ими, которые добавляют обогащение ИИ в прием данных.
Создание анализаторов для расширенного анализа текста или многоязычного содержимого и управление ими.
Оптимизируйте результаты с помощью профилей семантического ранжирования и оценки, чтобы учитывать бизнес-логику или свежесть.

Ключевые ссылки:

Начало работы

Установите пакет `@azure/search-documents`.

npm install @azure/search-documents

Поддерживаемые в настоящее время среды

Версии Node.js LTS
Последние версии Safari, Chrome, Microsoft Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Необходимые условия

Чтобы создать новую службу поиска, можно использовать портал Azure, Azure PowerShell или Azure CLI. Ниже приведен пример использования Azure CLI для создания бесплатного экземпляра для начала работы:

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

Дополнительные сведения о доступных вариантах см. в разделе Выбор ценовой категории .

Проверка подлинности клиента

Для взаимодействия с поисковым сервисом необходимо создать экземпляр соответствующего клиентского класса: SearchClient для поиска индексированных документов, SearchIndexClient для управления индексами или SearchIndexerClient для обхода источников данных и загрузки поисковых документов в индекс. Чтобы создать экземпляр клиентского объекта, вам потребуется конечная точка и роли Azure или ключ API. Дополнительные сведения о поддерживаемых подходах к проверке подлинности с помощью службы поиска см. в документации.

Получение ключа API

Ключ API может быть более простым подходом для начала, так как он не требует предварительно существующих назначений ролей.

Вы можете получить конечную точку и ключ API из службы поиска на портале Azure. Пожалуйста, обратитесь к документации за инструкциями о том, как получить ключ API.

Кроме того, можно использовать следующую команду Azure CLI для получения ключа API из службы поиска:

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

Существует два типа ключей, используемых для доступа к службе поиска: ключи admin(чтение-запись) и ключи query(только для чтения). Ограничение доступа и операций в клиентских приложениях важно для защиты ресурсов поиска в службе. Всегда используйте ключ запроса, а не ключ администратора для любого запроса, исходя из клиентского приложения.

Примечание: Приведенный выше пример фрагмента кода Azure CLI извлекает ключ администратора, чтобы упростить начало изучения API, но с ним следует обращаться осторожно.

Получив ключ API, его можно использовать следующим образом:

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

Проверка подлинности в национальном облаке

Чтобы пройти аутентификацию в национальном облаке, вам потребуется внести следующие дополнения в конфигурацию клиента:

Установите Audience вход 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,
});

Основные понятия

Служба поиска ИИ Azure содержит один или несколько индексов, которые обеспечивают постоянное хранение данных, доступных для поиска, в виде документов JSON. (Если вы новичок в поиске, вы можете провести очень грубую аналогию между индексами и таблицами базы данных.) Клиентская @azure/search-documents библиотека предоставляет операции с этими ресурсами через три основных типа клиентов.

SearchClient Помогает при:
- Поиск индексированных документов с помощью векторных запросов, запросов по ключевым словам и гибридных запросов
- Фильтры векторных запросов и фильтры текстовых запросов
- Семантическое ранжирование и профили оценки для повышения релевантности
- Автозаполнение частично набранных поисковых терминов на основе документов в индексе
- Предложение наиболее вероятного совпадающего текста в документах в качестве пользовательских типов
- Добавление, обновление или удаление документов из индекса
SearchIndexClient предоставляет следующие возможности:
- Создание, удаление, обновление или настройка индекса поиска
- Объявление пользовательских сопоставлений синонимов для расширения или переписывания запросов
SearchIndexerClient предоставляет следующие возможности:
- Запуск индексаторов для автоматического обхода источников данных
- Определите наборы навыков на основе искусственного интеллекта для преобразования и обогащения данных

Примечание: Эти клиенты не могут работать в браузере, потому что API, которые они вызывают, не поддерживают общий доступ к ресурсам независимо от источника (CORS).

Основные понятия TypeScript и JavaScript

Документы

Элемент, хранящийся в индексе поиска. Форма этого документа описывается в индексе с помощью fields свойства. У каждого из них SearchField есть имя, тип данных и дополнительные метаданные, например возможность поиска или фильтрации.

Нумерация страниц

Как правило, пользователю требуется показать только подмножество результатов поиска за один раз. Для этого можно использовать topпараметры , skip and includeTotalCount , чтобы обеспечить постраничное взаимодействие поверх результатов поиска.

Кодировка поля документа

Поддерживаемые типы данных в индексе сопоставляются с типами JSON в запросах и ответах API. Клиентская библиотека JS в основном сохраняет такие же, причем некоторые исключения:

Edm.DateTimeOffset преобразуется в JS Date.
Edm.GeographyPoint преобразуется в тип, экспортируемый GeographyPoint клиентской библиотекой.
Специальные значения number типа (NaN, Infinity, -Infinity) сериализуются как строки в REST API, но преобразуются обратно клиентской number библиотекой.

Примечание: Типы данных преобразуются на основе значения, а не типа поля в схеме индекса. Это означает, что если у вас есть строка даты ISO8601 (например, "2020-03-06T18:48:27.896Z") в качестве значения поля, оно будет преобразовано в дату независимо от того, как он хранится в схеме.

Примеры

Следующие примеры демонстрируют основы - пожалуйста , ознакомьтесь с нашими примерами , чтобы узнать больше.

Создание индекса
Извлечение определенного документа из индекса
Добавление документов в индекс
Выполнение поиска по документам

Создание индекса

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}`);

Получение определенного документа из индекса

Определенный документ можно получить по значению первичного ключа:

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

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

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

Добавление документов в индекс

Можно передать несколько документов в индекс внутри пакета:

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}`);
}

Выполнение поиска по документам

Чтобы получить список всех результатов определенного запроса, вы можете использовать search строку поиска, которая использует простой синтаксис запроса:

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

Для более сложного поиска, использующего синтаксис Lucene, укажите queryType следующее 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);
}

Запрос с помощью TypeScript

В TypeScript принимает общий параметр, SearchClient который является модельной формой индексных документов. Это позволяет выполнять строго типизированный поиск полей, возвращаемых в результатах. TypeScript также умеет проверять поля, возвращаемые при указании параметра 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 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);
}

Запросы с помощью фильтров OData

Использование параметра filter query позволяет запрашивать индекс с использованием синтаксиса выражения 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);
}

Запрос с помощью векторов

К встраиванию текста можно обращаться с помощью параметра vector search. Дополнительные сведения см. в разделах Векторы запросов и Запросы с помощью фильтров .

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

Фасеты используются для того, чтобы помочь пользователю приложения уточнить поиск по предварительно настроенным параметрам. Синтаксис фасетов предоставляет возможности сортировки и сегментирования значений фасетов.

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

При получении результатов будет доступно свойство facets , которое будет указывать количество результатов, попадающих в каждый сегмент фасетов. Это может быть использовано для уточнения (например, для последующего поиска, который фильтрует по значению, большему Rating или равному 3 и меньшему 4).

Устранение неполадок

Лесозаготовка

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Дальнейшие действия

Способствует

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по созданию и тестированию кода.

Этот проект приветствует взносы и предложения. Большинство вкладов требуют, чтобы вы согласились с соглашением о лицензии участника (CLA), заявив, что у вас есть право, и на самом деле, предоставьте нам права на использование вашего вклада. Для получения подробной информации посетите cla.microsoft.com.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Для получения дополнительной информации см. FAQ о кодексе поведения, или свяжитесь с [email protected] по любым дополнительным вопросам или комментариям.

Пакет SDK Microsoft Azure для JavaScript

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-10-10