Bibliothèque de client REST d’inférence Azure pour JavaScript - version 1.0.0-beta.4

Article
11/07/2024

API d’inférence pour les modèles IA pris en charge par Azure

S’il vous plaît s’appuyer fortement sur nos documents clients REST pour utiliser cette bibliothèque

Liens clés :

code source
package (NPM)
Documentation de référence de l’API
Exemples

Commencer

import ModelClient, { isUnexpected } from "@azure-rest/ai-inference";
import { AzureKeyCredential } from "@azure/core-auth";
const client = new ModelClient(
  "https://<Azure Model endpoint>",
  new AzureKeyCredential("<Azure API key>")
);

const response = await client.path("/chat/completions").post({
  body: {
    messages: [
      {role: "user", content: "How many feet are in a mile?"},
    ],
  }
});

if(isUnexpected(response)) {
  throw response.body.error;
}
console.log(response.body.choices[0].message.content);

Environnements actuellement pris en charge

Versions LTS de Node.js

Conditions préalables

Vous devez disposer d’un abonnement Azure pour utiliser ce package.

Installer le package `@azure-rest/ai-inference`

Installez la bibliothèque de client REST du client REST Azure ModelClient pour JavaScript avec npm:

npm install @azure-rest/ai-inference

Créer et authentifier un `ModelClient`

Utilisation d’une clé API à partir d’Azure

Vous pouvez vous authentifier avec une clé API Azure à l’aide de la bibliothèque d’authentification Azure Core . Pour utiliser le fournisseur AzureKeyCredential indiqué ci-dessous, installez le package @azure/core-auth :

npm install @azure/core-auth

Utilisez le portail Azure pour accéder à votre déploiement de modèle et récupérer une clé API.

Remarque : Parfois, la clé API est appelée « clé d’abonnement » ou « clé API d’abonnement ».

Une fois que vous disposez d’une clé API et d’un point de terminaison, vous pouvez utiliser la classe AzureKeyCredential pour authentifier le client comme suit :

import ModelClient from "@azure-rest/ai-inference";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new ModelClient("<endpoint>", new AzureKeyCredential("<API key>"));

Utilisation d’informations d’identification Azure Active Directory

Vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le package :

npm install @azure/identity

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

import ModelClient from "@azure-rest/ai-inference";
import { DefaultAzureCredential }  from "@azure/identity";

const client = new ModelClient("<endpoint>", new DefaultAzureCredential());

Concepts clés

Le concept principal à comprendre est achèvements. Brièvement expliqué, les saisies semi-automatiques fournissent ses fonctionnalités sous la forme d’une invite de texte, qui, à l’aide d’un modèle spécifique, tente ensuite de correspondre au contexte et aux modèles, en fournissant un texte de sortie. L’extrait de code suivant fournit une vue d’ensemble approximative :

import ModelClient, { isUnexpected } from "@azure-rest/ai-inference";
import { AzureKeyCredential } from "@azure/core-auth";

async function main(){
  const client = new ModelClient(
  "https://your-model-endpoint/",
  new AzureKeyCredential("your-model-api-key"));

  const response = await client.path("/chat/completions").post({
    body: {
      messages: [
        {role: "user", content: "Hello, world!"},
      ],
    }
  });

  if(isUnexpected(response)) {
    throw response.body.error;
  }

  console.log(response.body.choices[0].message.content);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Exemples

Générer une réponse de chatbot

La conversation en continu avec le Kit de développement logiciel (SDK) d’inférence nécessite une prise en charge principale de la diffusion en continu ; pour activer cette prise en charge, installez le package @azure/core-sse :

npm install @azure/core-sse

Cet exemple s’authentifie à l’aide d’un DefaultAzureCredential, puis génère des réponses de conversation pour entrer la question de conversation et les messages.

import ModelClient from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";
import { createSseStream } from "@azure/core-sse";

async function main(){
  const endpoint = "https://myaccount.openai.azure.com/";
  const client = new ModelClient(endpoint, new DefaultAzureCredential());

  const messages = [
    // NOTE: "system" role is not supported on all Azure Models
    { role: "system", content: "You are a helpful assistant. You will talk like a pirate." },
    { role: "user", content: "Can you help me?" },
    { role: "assistant", content: "Arrrr! Of course, me hearty! What can I do for ye?" },
    { role: "user", content: "What's the best way to train a parrot?" },
  ];

  console.log(`Messages: ${messages.map((m) => m.content).join("\n")}`);

  const response = await client.path("/chat/completions").post({
    body: {
      messages,
      stream: true,
      max_tokens: 128
    }
  }).asNodeStream();

  const stream = response.body;
  if (!stream) {
    throw new Error("The response stream is undefined");
  }

  if (response.status !== "200") {
    throw new Error(`Failed to get chat completions: ${response.body.error}`);
  }

  const sses = createSseStream(stream);

  for await (const event of sses) {
    if (event.data === "[DONE]") {
      return;
    }
    for (const choice of (JSON.parse(event.data)).choices) {
      console.log(choice.delta?.content ?? "");
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Générer plusieurs saisies semi-automatiques avec la clé d’abonnement

Cet exemple génère des réponses textuelles aux invites d’entrée à l’aide d’une clé d’abonnement Azure

import ModelClient from "@azure-rest/ai-inference";
import { AzureKeyCredential } from "@azure/core-auth";

async function main(){
  // Replace with your Model API key
  const key = "YOUR_MODEL_API_KEY";
  const endpoint = "https://your-model-endpoint/";
  const client = new ModelClient(endpoint, new AzureKeyCredential(key));

  const messages = [
    { role: "user", content: "How are you today?" },
    { role: "user", content: "What is inference in the context of AI?" },
    { role: "user", content: "Why do children love dinosaurs?" },
    { role: "user", content: "Generate a proof of Euler's identity" },
    { role: "user", content: "Describe in single words only the good things that come into your mind about your mother." },
  ];

  let promptIndex = 0;
  const response = await client.path("/chat/completions").post({
    body: {
      messages
    }
  });

  if(response.status !== "200") {
    throw response.body.error;
  }
  for (const choice of response.body.choices) {
    const completion = choice.message.content;
    console.log(`Input: ${messages[promptIndex++].content}`);
    console.log(`Chatbot: ${completion}`);
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Résumer le texte avec saisie semi-automatique

Cet exemple génère un résumé de l’invite d’entrée donnée.

import ModelClient from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

async function main(){
  const endpoint = "https://your-model-endpoint/";
  const client = new ModelClient(endpoint, new DefaultAzureCredential());

  const textToSummarize = `
    Two independent experiments reported their results this morning at CERN, Europe's high-energy physics laboratory near Geneva in Switzerland. Both show convincing evidence of a new boson particle weighing around 125 gigaelectronvolts, which so far fits predictions of the Higgs previously made by theoretical physicists.

    ""As a layman I would say: 'I think we have it'. Would you agree?"" Rolf-Dieter Heuer, CERN's director-general, asked the packed auditorium. The physicists assembled there burst into applause.
  :`;

  const summarizationPrompt = `
    Summarize the following text.

    Text:
    """"""
    ${textToSummarize}
    """"""

    Summary:
  `;

  console.log(`Input: ${summarizationPrompt}`);

  const response = await client.path("/chat/completions").post({
    body: {
      messages: [
        { role: "user", content: summarizationPrompt }
      ],
      max_tokens: 64
    }
  });

  if(response.status !== "200") {
    throw response.body.error;
  }
  const completion = response.body.choices[0].message.content;
  console.log(`Summarization: ${completion}`);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Utiliser les outils de conversation

Outils étendre les achèvements de conversation en permettant à un assistant d’appeler des fonctions définies et d’autres fonctionnalités dans le processus de réalisation d’une demande d’achèvement de conversation. Pour utiliser des outils de conversation, commencez par définir un outil de fonction :

const getCurrentWeather = {
    name: "get_current_weather",
    description: "Get the current weather in a given location",
    parameters: {
      type: "object",
      properties: {
        location: {
          type: "string",
          description: "The city and state, e.g. San Francisco, CA",
        },
        unit: {
          type: "string",
          enum: ["celsius", "fahrenheit"],
        },
      },
      required: ["location"],
    },
  };

Avec l’outil défini, incluez cette nouvelle définition dans les options d’une demande d’achèvement de conversation :

const messages = [{ role: "user", content: "What is the weather like in Boston?" }];
const tools = [
  {
    type: "function",
    function: getCurrentWeather,
  },
];
const result = await client.path("/chat/completions").post({
  body: {
    messages,
    tools
  }
});

Lorsque l’Assistant décide qu’un ou plusieurs outils doivent être utilisés, le message de réponse inclut un ou plusieurs « appels d’outils » qui doivent tous être résolus via des « messages d’outil » sur la demande suivante. Cette résolution des appels d’outils dans de nouveaux messages de requête peut être considérée comme une sorte de « rappel » pour les achèvements de conversation.

// Purely for convenience and clarity, this function handles tool call responses.
function applyToolCall({ function: call, id }) {
    if (call.name === "get_current_weather") {
      const { location, unit } = JSON.parse(call.arguments);
      // In a real application, this would be a call to a weather API with location and unit parameters
      return {
        role: "tool",
        content: `The weather in ${location} is 72 degrees ${unit} and sunny.`,
        toolCallId: id,
      }
    }
    throw new Error(`Unknown tool call: ${call.name}`);
}

Pour fournir des résolutions d’appel d’outil à l’Assistant pour permettre à la demande de continuer, fournissez tout le contexte historique précédent, y compris les messages système et utilisateur d’origine, la réponse de l’Assistant qui incluait les appels d’outils et les messages d’outil qui ont résolu chacun de ces outils - lors de la création d’une demande ultérieure.

const choice = result.body.choices[0];
const responseMessage = choice.message;
if (responseMessage?.role === "assistant") {
  const requestedToolCalls = responseMessage?.toolCalls;
  if (requestedToolCalls?.length) {
    const toolCallResolutionMessages = [
      ...messages,
      responseMessage,
      ...requestedToolCalls.map(applyToolCall),
    ];
    const toolCallResolutionResult = await client.path("/chat/completions").post({
      body: {
        messages: toolCallResolutionMessages
      }
    });
    // continue handling the response as normal
  }
}

Discuter avec des images (à l’aide de modèles prenant en charge la conversation d’image, comme gpt-4o)

Certains modèles Azure vous permettent d’utiliser des images comme composants d’entrée dans les saisies semi-automatiques de conversation.

Pour ce faire, fournissez des éléments de contenu distincts sur le ou les messages utilisateur pour la demande de saisie semi-automatique de conversation :

const url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
const messages = [{
    role: "user", content: [{
    type: "image_url",
    image_url: {
      url,
      detail: "auto"
    }
  }]},
  {role: "user", content: "describe the image"}];

Les saisies semi-automatiques de conversation seront ensuite effectuées comme d’habitude, bien que le modèle puisse signaler les finish_details plus informatifs au lieu de finish_reason:

const response = await client.path("/chat/completions").post({
  body: {
    messages 
});
console.log(`Chatbot: ${response.choices[0].message?.content}`);

Exemple d’incorporation de texte

Cet exemple montre comment obtenir des incorporations de texte avec l’authentification Entra ID.

import ModelClient, { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "<your_model_endpoint>";
const credential = new DefaultAzureCredential();

async function main(){
  const client = ModelClient(endpoint, credential);
  const response = await client.path("/embeddings").post({
    body: {
      input: ["first phrase", "second phrase", "third phrase"]
    }
  });

  if (isUnexpected(response)) {
    throw response.body.error;
  }
  for (const data of response.body.data) {
    console.log(`data length: ${data.length}, [${data[0]}, ${data[1]}, ..., ${data[data.length - 2]}, ${data[data.length - 1]}]`);
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

La longueur du vecteur d’incorporation dépend du modèle, mais vous devez voir quelque chose comme suit :

data: length=1024, [0.0013399124, -0.01576233, ..., 0.007843018, 0.000238657]
data: length=1024, [0.036590576, -0.0059547424, ..., 0.011405945, 0.004863739]
data: length=1024, [0.04196167, 0.029083252, ..., -0.0027484894, 0.0073127747]

Pour générer des incorporations pour des expressions supplémentaires, appelez simplement client.path("/embeddings").post plusieurs fois à l’aide du même client.

Instrumentation

Actuellement, l’instrumentation n’est prise en charge que pour Chat Completion without streaming. Pour activer l’instrumentation, il est nécessaire d’inscrire des exportateurs.

Voici un exemple d’ajout de console en tant qu’exportateur :

import { ConsoleSpanExporter, NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node";

const provider = new NodeTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.register();

Voici un exemple d’ajout d’insights d’application pour être un exportateur :

import { NodeTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node";
import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";

// provide a connection string
const connectionString = "<connection string>";

const provider = new NodeTracerProvider();
if (connectionString) {
  const exporter = new AzureMonitorTraceExporter({ connectionString });
  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
}
provider.register();

Pour utiliser l’instrumentation pour le Kit de développement logiciel (SDK) Azure, vous devez l’inscrire avant d’importer des dépendances à partir de @azure/core-tracing, telles que @azure-rest/ai-inference.

import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk";

registerInstrumentations({
  instrumentations: [createAzureSdkInstrumentation()],
});

import ModelClient from "@azure-rest/ai-inference";

Enfin, lorsque vous effectuez un appel pour la fin de la conversation, vous devez inclure

tracingOptions: { tracingContext: context.active() }

Voici un exemple :

import { context } from "@opentelemetry/api";
client.path("/chat/completions").post({
      body: {...},
      tracingOptions: { tracingContext: context.active() }
});

Suivi de vos propres fonctions

Open Telemetry fournit startActiveSpan pour instrumenter votre propre code. Voici un exemple :

import { trace } from "@opentelemetry/api";
const tracer = trace.getTracer("sample", "0.1.0");

const getWeatherFunc = (location: string, unit: string): string => {
  return tracer.startActiveSpan("getWeatherFunc", span => {
    if (unit !== "celsius") {
      unit = "fahrenheit";
    }
    const result = `The temperature in ${location} is 72 degrees ${unit}`;
    span.setAttribute("result", result);
    span.end();
    return result;
  });
}

Dépannage

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, vous pouvez consulter la documentationdu package @azure/enregistreur d’événements.

Partager via

Bibliothèque de client REST d’inférence Azure pour JavaScript - version 1.0.0-beta.4

Commencer

Environnements actuellement pris en charge

Conditions préalables

Installer le package `@azure-rest/ai-inference`

Créer et authentifier un `ModelClient`

Utilisation d’une clé API à partir d’Azure

Utilisation d’informations d’identification Azure Active Directory

Concepts clés

Exemples

Générer une réponse de chatbot

Générer plusieurs saisies semi-automatiques avec la clé d’abonnement

Résumer le texte avec saisie semi-automatique

Utiliser les outils de conversation

Discuter avec des images (à l’aide de modèles prenant en charge la conversation d’image, comme gpt-4o)

Exemple d’incorporation de texte

Instrumentation

Suivi de vos propres fonctions

Dépannage

Exploitation forestière

Ressources supplémentaires

Partager via

Bibliothèque de client REST d’inférence Azure pour JavaScript - version 1.0.0-beta.4

Commencer

Environnements actuellement pris en charge

Conditions préalables

Installer le package @azure-rest/ai-inference

Créer et authentifier un ModelClient

Utilisation d’une clé API à partir d’Azure

Utilisation d’informations d’identification Azure Active Directory

Concepts clés

Exemples

Générer une réponse de chatbot

Générer plusieurs saisies semi-automatiques avec la clé d’abonnement

Résumer le texte avec saisie semi-automatique

Utiliser les outils de conversation

Discuter avec des images (à l’aide de modèles prenant en charge la conversation d’image, comme gpt-4o)

Exemple d’incorporation de texte

Instrumentation

Suivi de vos propres fonctions

Dépannage

Exploitation forestière

Ressources supplémentaires

Installer le package `@azure-rest/ai-inference`

Créer et authentifier un `ModelClient`