Клиентская библиотека поиска ИИ Azure для JavaScript версии 12.1.0

Статья
08/03/2024

поиска ИИ Azure (прежнее название — "Когнитивный поиск Azure") — это платформа получения сведений с использованием искусственного интеллекта, которая помогает разработчикам создавать широкие возможности поиска и создавать большие языковые модели с корпоративными данными.

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

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

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

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

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

исходный код
пакета (NPM)
Справочная документация по API
документации по REST API
документации по продукту
примеры

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

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

npm install @azure/search-documents

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

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

Дополнительные сведения см. в политике поддержки .

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

подписки Azure
службы поиска

Чтобы создать новую службу поиска, можно использоватьпортала 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>

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

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

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

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

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

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

Настройка Audience в 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,
});

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

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

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

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

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

Документы

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

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

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

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

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

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

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

Примеры

В следующих примерах показано основные сведения. ознакомьтесь с нашими примерами для получения дополнительных сведений.

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

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

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

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

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

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

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

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

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

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

Для перечисления всех результатов конкретного запроса можно использовать search со строкой поиска, используюющей простой синтаксис запросов:

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

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

Запрос с помощью 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 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();

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

Использование параметра запроса позволяет запрашивать индекс с помощью синтаксисавыражения OData $filter.

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

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

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

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

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

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

При получении результатов будет доступно свойство 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.

Этот проект принял Microsoft Open Source Code of Conduct. Дополнительные сведения см. в кодекса поведения или с дополнительными вопросами или комментариями.

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

впечатлений

Поделиться через

Клиентская библиотека поиска ИИ Azure для JavaScript версии 12.1.0

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

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

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

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

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

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

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

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

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

Документы

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

Примеры

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

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

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

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

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

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

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

Запрос с аспектами

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

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

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

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

Дополнительные ресурсы

Поделиться через

Клиентская библиотека поиска ИИ Azure для JavaScript версии 12.1.0

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

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

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

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

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

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

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

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

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

Документы

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

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

Примеры

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

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

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

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

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

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

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

Запрос с аспектами

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

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

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

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

Связанные проекты

Дополнительные ресурсы

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