Клиентская библиотека проектов Azure AI для JavaScript версии 1.0.0-beta.10

Клиентская библиотека AI Projects обеспечивает простой доступ к ресурсам в проекте Azure AI Foundry. Он используется для следующих задач:

• Создайте и запустите агенты с помощью .agents свойства на клиенте.
• Получите клиент AzureOpenAI с помощью этого метода .inference.azureOpenAI .
• Перечислите модели ИИ , развернутые в проекте Foundry, .deployments с помощью операций.
• Перечислите подключенные ресурсы Azure в проекте Foundry с помощью .connections операций.
• Загрузите документы и создайте наборы данных , чтобы ссылаться на них с помощью .datasets операций.
• Создание и перечисление индексов поиска с помощью .indexes операций.
• Получите клиент вывода Azure AI для завершения чата, внедрения текста или изображений с помощью .inference операций.
• Чтение файла или строки Prompty и рендеринг сообщений для клиентов вывода с помощью PromptTemplate класса.
• Выполнение оценок для оценки производительности приложений генеративного ИИ с помощью evaluations операций.
• Включите трассировку OpenTelemetry с помощью enable_telemetry этой функции.

Документация по продукту | Образцы | Упаковка (npm) | Справочная документация | по APIИсходный код SDK

Оглавление

• начало работы
  • предварительные требования
  • Авторизация
  • Установка пакета
• основные понятия
  • Создание и проверка подлинности клиента
• примеры
  • Выполнение операций с Агентом
  • Получение аутентифицированного клиента AzureOpenAI
  • Получение аутентифицированного клиента ChatCompletions
  • Операции по развертыванию
  • Операции с подключениями
  • Операции с набором данных
  • Операции с индексами
  • Оценка
    • Вычислитель
    • Выполнение оценки в облаке
    • Пример удаленной оценки
• устранение неполадок
  • исключений
  • проблемы с отчетами
• Дальнейшие действия
• участие

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

Предпосылка

• версии LTS Node.js
• подписка Azure.
• Проект в Azure AI Foundry.

Авторизация

• Entra ID необходим для аутентификации клиента. Приложению требуется объект, реализующий интерфейс TokenCredential. Примеры кода здесь используют DefaultAzureCredential. Чтобы получить эту работу, вам потребуется:
  • Роль Contributor. На портале Azure можно назначить роль с помощью вкладки "Управление доступом (IAM)" ресурса проекта Azure AI. Подробнее о назначении ролей можно узнать здесь.
  • установленной Azure CLI.
  • Вы вошли в учетную запись Azure, выполнив az login.
  • Обратите внимание, что если у вас несколько подписок Azure, подписка, содержащая ресурс Проекта Azure AI, должна быть вашей подпиской по умолчанию. Запустите az account list --output table, чтобы вывести список всех подписок и увидеть, какой из них используется по умолчанию. Запустите az account set --subscription "Your Subscription ID or Name", чтобы изменить подписку по умолчанию.

Установка пакета

npm install @azure/ai-projects @azure/identity

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

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

Чтобы создать , AIProjectsClientможно endpoint получить из конечной точки. Ниже мы предположим, что переменная AZURE_AI_PROJECT_ENDPOINT_STRING окружения была определена для хранения этого значения:

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = process.env["AZURE_AI_PROJECT_ENDPOINT_STRING"] || "<project endpoint string>";
const client = new AIProjectClient(endpoint, new DefaultAzureCredential());

Клиент использует версию 2025-05-15-previewAPI, обратитесь к документации API , чтобы узнать больше о поддерживаемых функциях.

Примеры

Выполнение операций с Агентом

Свойство .agents на the AIProjectClient предоставляет вам доступ к аутентификации AgentsClient из пакета azure-ai-agents . Ниже мы покажем, как создать агента и удалить его. Чтобы узнать, что можно сделать с созданным пакетом agent , ознакомьтесь с множеством примеров , связанных с пакетом azure-ai-agents .

const agent = await project.agents.createAgent("gpt-4o", {
  name: "my-agent",
  instructions: "You are a helpful agent",
});
console.log(`Created agent, agent ID : ${agent.id}`);

// Do something with your Agent!
// See samples here https://github.com/Azure/azure-sdk-for-js/tree/@azure/ai-projects_1.0.0-beta.10/sdk/ai/ai-agents/samples
await project.agents.deleteAgent(agent.id);
console.log(`Deleted agent, agent ID: ${agent.id}`);

Получение аутентифицированного клиента AzureOpenAI

В проекте Azure AI Foundry может быть развернута одна или несколько моделей OpenAI, поддерживающих завершение чата. Используйте приведенный ниже код, чтобы получить аутентифицированный AzureOpenAI из пакета openai и выполнить вызов завершения чата.

Выполните приведенный ниже код. Здесь мы предполагаем, что deploymentName (str) определено. Это имя развертывания модели ИИ в проекте Foundry. Как показано во вкладке "Модели + конечные точки", в столбце "Название".

Обновите значение на значение, найденное api_version в строке "Плоскость данных - вывод" в этой таблице.

У вас также есть возможность (не показана) явно указать имя подключения Azure OpenAI в проекте AI Foundry, которое метод inference.azureOpenAI будет использовать для получения конечной точки вывода и учетных данных для проверки подлинности. Если он отсутствует, будет использоваться подключение Azure OpenAI по умолчанию.

const client = await project.inference.azureOpenAI({
  // The API version should match the version of the Azure OpenAI resource.
  apiVersion: "2024-10-21",
});
const response = await client.chat.completions.create({
  model: deploymentName,
  messages: [{ role: "user", content: "How many feet are in a mile?" }],
});
console.log("response = ", JSON.stringify(response, null, 2));

Дополнительные примеры см. в папке "inference" в примерах пакета .

Получение аутентифицированного клиента ChatCompletions

В проекте Azure AI Foundry может быть развернута одна или несколько моделей ИИ, поддерживающих завершение чата. Это могут быть модели OpenAI, Microsoft или модели других поставщиков. Используйте приведенный ниже код, чтобы получить аутентифицированный клиент и выполнить звонок по завершению чата.

Здесь мы предполагаем, что deploymentName (str) определено. Это имя развертывания модели ИИ в проекте Foundry. Как показано во вкладке "Модели + конечные точки", в столбце "Название".

const client = project.inference.chatCompletions();
const response = await client.post({
  body: {
    model: deploymentName,
    messages: [{ role: "user", content: "How many feet are in a mile?" }],
  },
});
console.log(response.body.choices[0].message.content);

Дополнительные примеры см. в папке "inference" в примерах пакета .

Операции по развертыванию

В приведенном ниже коде показаны некоторые операции развертывания, которые позволяют перечислить модели ИИ, развернутые в проектах AI Foundry. Эти модели можно увидеть на вкладке «Модели + конечные точки» в вашем проекте AI Foundry. Полные примеры можно найти в папке "deployment" в образцах пакета.

import { ModelDeployment } from "@azure/ai-projects";

const modelPublisher = process.env["MODEL_PUBLISHER"] || "<model publisher>";
console.log("List all deployments:");
const deployments: ModelDeployment[] = [];
const properties: Array<Record<string, string>> = [];

for await (const deployment of project.deployments.list()) {
  // Check if this is a ModelDeployment (has the required properties)
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    deployments.push(deployment);
    properties.push({
      name: deployment.name,
      modelPublisher: deployment.modelPublisher,
      modelName: deployment.modelName,
    });
  }
}
console.log(`Retrieved deployments: ${JSON.stringify(properties, null, 2)}`);

// List all deployments by a specific model publisher (assuming we have one from the list)
console.log(`List all deployments by the model publisher '${modelPublisher}':`);
const filteredDeployments: ModelDeployment[] = [];
for await (const deployment of project.deployments.list({
  modelPublisher,
})) {
  // Check if this is a ModelDeployment
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    filteredDeployments.push(deployment);
  }
}
console.log(
  `Retrieved ${filteredDeployments.length} deployments from model publisher '${modelPublisher}'`,
);

// Get a single deployment by name
if (deployments.length > 0) {
  const deploymentName = deployments[0].name;
  console.log(`Get a single deployment named '${deploymentName}':`);
  const singleDeployment = await project.deployments.get(deploymentName);
  console.log(`Retrieved deployment: ${JSON.stringify(singleDeployment, null, 2)}`);
}

Операции с подключениями

В приведенном ниже коде показаны некоторые операции подключения, которые позволяют перечислить ресурсы Azure, подключенные к проектам AI Foundry. Эти подключения можно увидеть в «Центре управления», во вкладке «Подключенные ресурсы» в вашем проекте AI Foundry. Полные примеры можно найти в папке connections в примерах пакетов.

import { Connection } from "@azure/ai-projects";

// List the details of all the connections
const connections: Connection[] = [];
const connectionNames: string[] = [];
for await (const connection of project.connections.list()) {
  connections.push(connection);
  connectionNames.push(connection.name);
}
console.log(`Retrieved connections: ${connectionNames}`);

// Get the details of a connection, without credentials
const connectionName = connections[0].name;
const connection = await project.connections.get(connectionName);
console.log(`Retrieved connection ${JSON.stringify(connection, null, 2)}`);

const connectionWithCredentials = await project.connections.getWithCredentials(connectionName);
console.log(
  `Retrieved connection with credentials ${JSON.stringify(connectionWithCredentials, null, 2)}`,
);

// List all connections of a specific type
const azureAIConnections: Connection[] = [];
for await (const azureOpenAIConnection of project.connections.list({
  connectionType: "AzureOpenAI",
  defaultConnection: true,
})) {
  azureAIConnections.push(azureOpenAIConnection);
}
console.log(`Retrieved ${azureAIConnections.length} Azure OpenAI connections`);

// Get the details of a default connection
const defaultConnection = await project.connections.getDefault("AzureOpenAI", true);
console.log(`Retrieved default connection ${JSON.stringify(defaultConnection, null, 2)}`);

Операции с набором данных

В приведенном ниже коде показаны некоторые операции с набором данных. Полные примеры можно найти в папке "datasets" в образцах пакета.

import { DatasetVersionUnion } from "@azure/ai-projects";

const VERSION1 = "1.0";
const VERSION2 = "2.0";
const VERSION3 = "3.0";

// sample files to use in the demonstration
const sampleFolder = "sample_folder";
// Create a unique dataset name for this sample run
const datasetName = `sample-dataset-basic`;
console.log("Upload a single file and create a new Dataset to reference the file.");
console.log("Here we explicitly specify the dataset version.");

const dataset1 = await project.datasets.uploadFile(
  datasetName,
  VERSION1,
  path.join(__dirname, sampleFolder, "sample_file1.txt"),
);
console.log("Dataset1 created:", JSON.stringify(dataset1, null, 2));

const credential = project.datasets.getCredentials(dataset1.name, dataset1.version, {});
console.log("Credential for the dataset:", credential);
console.log(
  "Upload all files in a folder (including subfolders) to the existing Dataset to reference the folder.",
);
console.log("Here again we explicitly specify a new dataset version");
const dataset2 = await project.datasets.uploadFolder(
  datasetName,
  VERSION2,
  path.join(__dirname, sampleFolder),
);
console.log("Dataset2 created:", JSON.stringify(dataset2, null, 2));
console.log(
  "Upload a single file to the existing dataset, while letting the service increment the version",
);
const dataset3 = await project.datasets.uploadFile(
  datasetName,
  VERSION3,
  path.join(__dirname, sampleFolder, "sample_file2.txt"),
);
console.log("Dataset3 created:", JSON.stringify(dataset3, null, 2));

console.log("Get an existing Dataset version `1`:");
const datasetVersion1 = await project.datasets.get(datasetName, VERSION1);
console.log("Dataset version 1:", JSON.stringify(datasetVersion1, null, 2));
console.log(`Listing all versions of the Dataset named '${datasetName}':`);
const datasetVersions = await project.datasets.listVersions(datasetName);
for await (const version of datasetVersions) {
  console.log("List versions:", version);
}
console.log("List latest versions of all Datasets:");
const latestDatasets = project.datasets.list();
for await (const dataset of latestDatasets) {
  console.log("List datasets:", dataset);
}
// List the details of all the datasets
const datasets = project.datasets.listVersions(datasetName);
const allDatasets: DatasetVersionUnion[] = [];
for await (const dataset of datasets) {
  allDatasets.push(dataset);
}
console.log(`Retrieved ${allDatasets.length} datasets`);
console.log("Delete all Datasets created above:");
await project.datasets.delete(datasetName, VERSION1);
await project.datasets.delete(datasetName, VERSION2);
await project.datasets.delete(datasetName, dataset3.version);
console.log("All specified Datasets have been deleted.");

Операции с индексами

В приведенном ниже коде показаны некоторые операции с индексами. Полные образцы можно найти в папке "indexes" в образцах пакета.

import { AzureAISearchIndex } from "@azure/ai-projects";

const indexName = "sample-index";
const version = "1";
const azureAIConnectionConfig: AzureAISearchIndex = {
  name: indexName,
  type: "AzureSearch",
  version,
  indexName,
  connectionName: "sample-connection",
};

// Create a new Index
const newIndex = await project.indexes.createOrUpdate(indexName, version, azureAIConnectionConfig);
console.log("Created a new Index:", newIndex);
console.log(`Get an existing Index version '${version}':`);
const index = await project.indexes.get(indexName, version);
console.log(index);
console.log(`Listing all versions of the Index named '${indexName}':`);
const indexVersions = project.indexes.listVersions(indexName);
for await (const indexVersion of indexVersions) {
  console.log(indexVersion);
}
console.log("List all Indexes:");
const allIndexes = project.indexes.list();
for await (const i of allIndexes) {
  console.log("Index:", i);
}
console.log("Delete the Index versions created above:");
await project.indexes.delete(indexName, version);

Оценка

Оценка в клиентской библиотеке Azure AI Project предназначена для оценки производительности приложений генеративного ИИ в облаке. Выходные данные приложения генеративного ИИ количественно измеряются с помощью математических показателей, показателей качества и безопасности с помощью ИИ. Метрики определяются как оценщики. Встроенные или пользовательские оценщики могут предоставить исчерпывающее представление о возможностях и ограничениях приложения.

Оценщик

Оценщики — это пользовательские или предварительно созданные классы или функции, предназначенные для измерения качества выходных данных языковых моделей или приложений генеративного ИИ.

Оценщики доступны через пакет SDK azure-ai-evaluation для локального взаимодействия, а также в библиотеке Evaluator в Azure AI Foundry для использования в облаке.

Более подробную информацию о встроенных и пользовательских оценщиках можно найти здесь.

Выполнение оценки в облаке

Для выполнения оценки в облаке необходимо:

• Оценщиков
• Данные для оценки
• [Необязательный] Модель Azure Open AI.

Оценщиков

Для запуска оценщика в облаке необходим оценщик ID . Чтобы получить его с помощью кода, вы используете azure-ai-evaluation

import { DatasetVersion } from "@azure/ai-projects";

const dataset: DatasetVersion = await project.datasets.uploadFile(
  "jss-eval-sample-dataset",
  "1",
  "./samples_folder/sample_data_evaluation.jsonl",
);

Данные для оценки

Оценка в облаке поддерживает данные в виде jsonl файла. Данные могут быть выгружены с помощью вспомогательного метода upload_file на клиенте проекта.

import { DatasetVersion } from "@azure/ai-projects";

const dataset: DatasetVersion = await project.datasets.uploadFile(
  "jss-eval-sample-dataset",
  "1",
  "./samples_folder/sample_data_evaluation.jsonl",
);

[Необязательный] Модель Azure OpenAI

Проект Azure AI Foundry поставляется с конечной точкой Azure Open AI по умолчанию, к которой можно легко получить доступ с помощью следующего кода. Это дает вам сведения о конечной точке Azure OpenAI. Некоторым оценщикам нужна модель, поддерживающая завершение чата.

const defaultConnection = await project.connections.getDefault("AzureOpenAI");

Пример удаленной оценки

import { EvaluationWithOptionalName, EvaluatorIds, Evaluation } from "@azure/ai-projects";

const newEvaluation: EvaluationWithOptionalName = {
  displayName: "Evaluation 1",
  description: "This is a test evaluation",
  data: {
    type: "dataset",
    id: "data-id", // dataset.name
  },
  evaluators: {
    relevance: {
      id: EvaluatorIds.RELEVANCE,
      initParams: {
        deploymentName: "gpt-4o-mini",
      },
      dataMapping: {
        query: "${data.query}",
        response: "${data.response}",
      },
    },
  },
};
const evalResp = await project.evaluations.create(newEvaluation);
console.log("Create a new evaluation:", JSON.stringify(evalResp, null, 2));
// get the evaluation by ID
const eval2 = await project.evaluations.get(evalResp.name);
console.log("Get the evaluation by ID:", eval2);

const evaluations: Evaluation[] = [];
const evaluationNames: string[] = [];
for await (const evaluation of project.evaluations.list()) {
  evaluations.push(evaluation);
  evaluationNames.push(evaluation.displayName ?? "");
}
console.log("List of evaluation display names:", evaluationNames);

// This is temporary, as interface recommend the name of the evaluation
const name = evaluations[0].name;
const evaluation = await project.evaluations.get(name);
console.log("Get an evaluation by ID:", JSON.stringify(evaluation, null, 2));

ПРИМЕЧАНИЕ: Сведения о локальном запуске оценщиков см. в статье Оценка с помощью пакета SDK для оценки Azure AI.

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

Исключения

Клиентские методы, которые вызывают службы, вызывают RestError для ответа кода состояния HTTP без успешного выполнения из службы. code исключения будет содержать код состояния HTTP-ответа. error.message исключения содержит подробное сообщение, которое может оказаться полезным при диагностике проблемы:

import { isRestError } from "@azure/core-rest-pipeline";

try {
  const result = await project.connections.list();
} catch (e) {
  if (isRestError(e)) {
    console.log(`Status code: ${e.code}`);
    console.log(e.message);
  } else {
    console.error(e);
  }
}

Например, если указать неправильные учетные данные:

Status code: 401 (Unauthorized)
Operation returned an invalid status 'Unauthorized'

Проблемы с отчетами

Чтобы сообщить о проблемах с клиентской библиотекой или запросить дополнительные функции, откройте проблему GitHub здесь

Дальнейшие шаги

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

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

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

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

Этот проект принял Microsoft Open Source Code of Conduct. Дополнительные сведения см. в разделе "Часто задаваемые вопросы о поведении" или [email protected] с дополнительными вопросами или комментариями.