Azure Inference REST-Clientbibliothek für JavaScript – Version 1.0.0-beta.4

Artikel
11/07/2024

Ableitungs-API für azure-unterstützte KI-Modelle

Verlassen Sie sich auf unsere REST-Clientdokumente, um diese Bibliothek

Wichtige Links:

Erste Schritte

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

Derzeit unterstützte Umgebungen

LTS-Versionen von Node.js

Voraussetzungen

Sie müssen über ein Azure-Abonnement verfügen,, um dieses Paket zu verwenden.

Installieren des `@azure-rest/ai-inference`-Pakets

Installieren Sie die Rest-Clientbibliothek des Azure ModelClient REST-Clients für JavaScript mit npm:

npm install @azure-rest/ai-inference

Erstellen und Authentifizieren einer `ModelClient`

Verwenden eines API-Schlüssels aus Azure

Sie können sich mit einem Azure-API-Schlüssel mithilfe der Azure Core Auth-Bibliothekauthentifizieren. Um den unten gezeigten AzureKeyCredential-Anbieter zu verwenden, installieren Sie das @azure/core-auth Paket:

npm install @azure/core-auth

Verwenden Sie das Azure Portal, um zu Ihrer Modellbereitstellung zu navigieren und einen API-Schlüssel abzurufen.

Hinweis: Manchmal wird der API-Schlüssel als "Abonnementschlüssel" oder "Abonnement-API-Schlüssel" bezeichnet.

Nachdem Sie über einen API-Schlüssel und einen Endpunkt verfügen, können Sie die AzureKeyCredential Klasse verwenden, um den Client wie folgt zu authentifizieren:

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

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

Verwenden von Azure Active Directory-Anmeldeinformationen

Sie können sich auch mit Azure Active Directory mithilfe der Azure Identity-Bibliothekauthentifizieren. Um den unten gezeigten DefaultAzureCredential Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie bitte das @azure/identity Paket:

npm install @azure/identity

Legen Sie die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: 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());

Schlüsselkonzepte

Das haupt zu verstehende Konzept ist Abschluss. Kurz erläutert, stellt die Fertigstellung ihre Funktionalität in Form einer Textaufforderung bereit, die mithilfe eines bestimmten Modells, dann versucht, den Kontext und die Muster abzugleichen und einen Ausgabetext bereitzustellen. Der folgende Codeausschnitt bietet eine grobe Übersicht:

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

Beispiele

Generieren einer Chatbot-Antwort

Streaming-Chat mit dem Inference SDK erfordert grundlegende Streamingunterstützung; um diesen Support zu aktivieren, installieren Sie bitte das @azure/core-sse Paket:

npm install @azure/core-sse

In diesem Beispiel wird mithilfe einer DefaultAzureCredential authentifiziert und dann Chatantworten für Eingabechatfragen und -nachrichten generiert.

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

Generieren mehrerer Fertigstellungen mit Abonnementschlüssel

In diesem Beispiel werden Textantworten für Eingabeaufforderungen mithilfe eines Azure-Abonnementschlüssels generiert.

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

Zusammenfassen von Text mit Abschluss

In diesem Beispiel wird eine Zusammenfassung der angegebenen Eingabeaufforderung generiert.

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

Verwenden von Chattools

Tools Chatabschlusse erweitern, indem ein Assistent definierte Funktionen und andere Funktionen im Prozess der Erfüllung einer Chatabschlussanfrage aufruft. Um Chattools zu verwenden, definieren Sie zunächst ein Funktionstool:

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"],
    },
  };

Fügen Sie diese neue Definition in die Optionen für eine Chatabschlussanfrage ein, wobei das Tool definiert ist:

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

Wenn der Assistent entscheidet, dass mindestens ein Tool verwendet werden soll, enthält die Antwortnachricht einen oder mehrere "Toolaufrufe", die alle über "Toolnachrichten" in der nachfolgenden Anforderung aufgelöst werden müssen. Diese Lösung von Toolanrufen in neue Anforderungsnachrichten kann als eine Art "Rückruf" für Chatabschlusse betrachtet werden.

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

Um dem Assistenten Toolanrufauflösungen bereitzustellen, damit die Anforderung fortgesetzt werden kann, stellen Sie alle vorherigen historischen Kontexte bereit – einschließlich der ursprünglichen System- und Benutzernachrichten, der Antwort des Assistenten, der die Toolaufrufe enthält, und die Toolmeldungen, die jedes dieser Tools gelöst haben – beim Ausführen einer nachfolgenden Anforderung.

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

Chatten mit Bildern (mithilfe von Modellen, die Bildchat unterstützen, z. B. gpt-4o)

Bei einigen Azure-Modellen können Sie Bilder als Eingabekomponenten in Chatabschluss verwenden.

Stellen Sie dazu unterschiedliche Inhaltselemente für die Benutzernachricht(en) für die Chatabschlussanfrage bereit:

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"}];

Chatabschlusse werden dann wie gewohnt fortgesetzt, obwohl das Modell die informativeren finish_details anstelle von finish_reasonmelden kann:

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

Beispiel für Texteinbettungen

In diesem Beispiel wird veranschaulicht, wie Texteinbettungen mit entra ID-Authentifizierung abgerufen werden.

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

Die Länge des Einbettungsvektors hängt vom Modell ab, aber Sie sollten etwas wie folgt sehen:

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]

Um Einbettungen für zusätzliche Ausdrücke zu generieren, rufen Sie einfach client.path("/embeddings").post mehrmals mit demselben clientauf.

Instrumentation

Derzeit wird die Instrumentierung nur für Chat Completion without streamingunterstützt. Zum Aktivieren der Instrumentierung ist es erforderlich, exporter(n) zu registrieren.

Hier ist ein Beispiel zum Hinzufügen der Konsole als Exporter:

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

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

Im Folgenden finden Sie ein Beispiel zum Hinzufügen von Anwendungseinblicken, um ein Exporter zu sein:

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

Um die Instrumentation für Das Azure SDK zu verwenden, müssen Sie sie registrieren, bevor Sie Abhängigkeiten aus @azure/core-tracingimportieren, z. B. @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";

Wenn Sie schließlich einen Anruf für den Chatabschluss tätigen, müssen Sie folgendes einschließen:

tracingOptions: { tracingContext: context.active() }

Hier ist ein Beispiel:

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

Nachverfolgen ihrer eigenen Funktionen

Open Telemetry stellt startActiveSpan bereit, um Ihren eigenen Code zu instrumentieren. Hier ist ein Beispiel:

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

Fehlerbehebung

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Freigeben über

Azure Inference REST-Clientbibliothek für JavaScript – Version 1.0.0-beta.4

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installieren des `@azure-rest/ai-inference`-Pakets

Erstellen und Authentifizieren einer `ModelClient`

Verwenden eines API-Schlüssels aus Azure

Verwenden von Azure Active Directory-Anmeldeinformationen

Schlüsselkonzepte

Beispiele

Generieren einer Chatbot-Antwort

Generieren mehrerer Fertigstellungen mit Abonnementschlüssel

Zusammenfassen von Text mit Abschluss

Verwenden von Chattools

Chatten mit Bildern (mithilfe von Modellen, die Bildchat unterstützen, z. B. gpt-4o)

Beispiel für Texteinbettungen

Instrumentation

Nachverfolgen ihrer eigenen Funktionen

Fehlerbehebung

Protokollierung

Zusätzliche Ressourcen

Freigeben über

Azure Inference REST-Clientbibliothek für JavaScript – Version 1.0.0-beta.4

Erste Schritte

Derzeit unterstützte Umgebungen

Voraussetzungen

Installieren des @azure-rest/ai-inference-Pakets

Erstellen und Authentifizieren einer ModelClient

Verwenden eines API-Schlüssels aus Azure

Verwenden von Azure Active Directory-Anmeldeinformationen

Schlüsselkonzepte

Beispiele

Generieren einer Chatbot-Antwort

Generieren mehrerer Fertigstellungen mit Abonnementschlüssel

Zusammenfassen von Text mit Abschluss

Verwenden von Chattools

Chatten mit Bildern (mithilfe von Modellen, die Bildchat unterstützen, z. B. gpt-4o)

Beispiel für Texteinbettungen

Instrumentation

Nachverfolgen ihrer eigenen Funktionen

Fehlerbehebung

Protokollierung

Zusätzliche Ressourcen

Installieren des `@azure-rest/ai-inference`-Pakets

Erstellen und Authentifizieren einer `ModelClient`