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

Статья
11/14/2023

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

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

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

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

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

Основные ссылки:

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

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

npm install @azure/search-documents

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

LTS версии Node.js
Последние версии Safari, Chrome, 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 --service-name <mysearch> --resource-group <mysearch-rg>

Получив ключ 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>"));

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

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

Установка в AudienceSearchClientOptions

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 библиотека предоставляет операции с этими ресурсами с помощью трех типов клиентов main.

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

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

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

Документы

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

Разбиение на страницы

Как правило, пользователю требуется одновременно отображать только подмножество результатов поиска . Для поддержки topэтого можно использовать параметры , skip и 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") в качестве значения поля, она будет преобразована в Date независимо от того, как вы сохранили ее в схеме.

Примеры

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

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

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

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

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

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

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

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 и средству ведения журнала.

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

Участие

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

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

В рамках этого проекта был принят Кодекс поведения с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе Вопросы и ответы по Кодексу поведения или свяжитесь opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

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

Просмотры

Share via

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

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

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

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

Предварительные требования

Аутентификация клиента

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

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

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

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

Документы

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

Примеры

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

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

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

Поиск документов

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

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

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

Запросы с использованием аспектов

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

Ведение журнала

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

Участие

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

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

Share via

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

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

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

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

Предварительные требования

Аутентификация клиента

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

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

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

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

Документы

Разбиение на страницы

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

Примеры

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

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

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

Поиск документов

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

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

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

Запросы с использованием аспектов

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

Ведение журнала

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

Участие

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

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

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

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