Compartir a través de

Biblioteca cliente rest de Inferencia de Azure para JavaScript: versión 1.0.0-beta.5

  • Artículo

API de inferencia para modelos de IA compatibles con Azure

Confíe en gran medida en nuestros documentos de cliente REST de para usar esta biblioteca

Vínculos clave:

  • código fuente
  • paquete de (NPM)
  • documentación de referencia de api de
  • ejemplos de

Empezar

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

Entornos admitidos actualmente

  • Versiones LTS de Node.js

Prerrequisitos

  • Debe tener una suscripción de Azure para usar este paquete.

Instalación del paquete @azure-rest/ai-inference

Instale la biblioteca de cliente REST rest de Azure ModelClient para JavaScript con npm:

npm install @azure-rest/ai-inference

Creación y autenticación de un ModelClient

Uso de una clave de API de Azure

Puede autenticarse con una clave de API de Azure mediante la biblioteca de autenticación de Azure Core . Para usar el proveedor AzureKeyCredential que se muestra a continuación, instale el paquete @azure/core-auth:

npm install @azure/core-auth

Use el Azure Portal para ir a la implementación del modelo y recuperar una clave de API.

Nota: A veces, la clave de API se conoce como "clave de suscripción" o "clave de API de suscripción".

Una vez que tenga una clave de API y un punto de conexión, puede usar la clase AzureKeyCredential para autenticar el cliente de la siguiente manera:

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

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

Uso de una credencial de Azure Active Directory

También puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure . Para usar el proveedor de de DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el paquete de :

npm install @azure/identity

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: 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());

Conceptos clave

El concepto principal para comprender es Finalizaciones. Se explica brevemente que las finalizaciones proporcionan su funcionalidad en forma de mensaje de texto, que mediante un modelo de específico, intentará entonces coincidir con el contexto y los patrones, proporcionando un texto de salida. El siguiente fragmento de código proporciona información general aproximada:

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

Ejemplos

Generar respuesta de bot de chat

El chat de streaming con el SDK de inferencia requiere compatibilidad con streaming principal; para habilitar esta compatibilidad, instale el paquete @azure/core-sse:

npm install @azure/core-sse

En este ejemplo se autentica mediante DefaultAzureCredential y, a continuación, se generan respuestas de chat a preguntas y mensajes de chat de entrada.

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

Generar varias finalizaciones con clave de suscripción

En este ejemplo se generan respuestas de texto a las solicitudes de entrada mediante una clave de suscripción de 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);
});

Resumir texto con finalización

En este ejemplo se genera un resumen del símbolo del sistema de entrada especificado.

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

Uso de herramientas de chat

Tools ampliar las finalizaciones de chat al permitir que un asistente invoque funciones definidas y otras funcionalidades en el proceso de completar una solicitud de finalización de chat. Para usar herramientas de chat, empiece por definir una herramienta de función:

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

Con la herramienta definida, incluya esa nueva definición en las opciones de una solicitud de finalización de chat:

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

Cuando el asistente decide que se deben usar una o varias herramientas, el mensaje de respuesta incluye una o varias "llamadas a herramientas" que deben resolverse a través de "mensajes de herramientas" en la solicitud posterior. Esta resolución de llamadas de herramienta a nuevos mensajes de solicitud se puede considerar como una especie de "devolución de llamada" para las finalizaciones de chat.

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

Para proporcionar resoluciones de llamada de herramienta al asistente para permitir que la solicitud continúe, proporcione todo el contexto histórico anterior, incluidos los mensajes originales del sistema y del usuario, la respuesta del asistente que incluyó las llamadas a la herramienta y los mensajes de herramienta que resolvieron cada una de esas herramientas, al realizar una solicitud posterior.

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

Chatear con imágenes (mediante modelos que admiten chat de imágenes, como gpt-4o)

Algunos modelos de Azure permiten usar imágenes como componentes de entrada en finalizaciones de chat.

Para ello, proporcione elementos de contenido distintos en los mensajes de usuario para la solicitud de finalización del chat:

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

Las finalizaciones de chat continuarán como de costumbre, aunque el modelo puede informar de la finish_details más informativa en lugar de finish_reason:

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

Ejemplo de incrustaciones de texto

En este ejemplo se muestra cómo obtener incrustaciones de texto con autenticación 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 longitud del vector de inserción depende del modelo, pero debería ver algo parecido a esto:

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]

Para generar incrustaciones para frases adicionales, simplemente llame a client.path("/embeddings").post varias veces con el mismo client.

Ejemplo de incrustaciones de imágenes

En este ejemplo se muestra cómo obtener incrustaciones de imágenes con autenticación entra ID.

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

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

function getImageDataUrl(imageFile, imageFormat) {
  try {
    const imageBuffer = fs.readFileSync(imageFile);
    const imageBase64 = imageBuffer.toString("base64");
    return `data:image/${imageFormat};base64,${imageBase64}`;
  } catch (error) {
    console.error(`Could not read '${imageFile}'.`);
    console.error("Set the correct path to the image file before running this sample.");
    process.exit(1);
  }
}

async function main() {
  const client = ModelClient(endpoint, credential);
  const image = getImageDataUrl("<image_file>", "<image_format>");
  const response = await client.path("/images/embeddings").post({
    body: {
      input: [{image}],
    },
  });

  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 longitud del vector de inserción depende del modelo, pero debería ver algo parecido a esto:

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]

Instrumentación

Actualmente, la instrumentación solo se admite para Chat Completion without streaming. Para habilitar la instrumentación, es necesario registrar exportadores.

Este es un ejemplo para agregar consola como exportador:

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

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

Este es un ejemplo para agregar información de aplicación para que sea un exportador:

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

Para usar la instrumentación de Azure SDK, debe registrarla antes de importar las dependencias de @azure/core-tracing, como @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";

Por último, cuando realice una llamada para finalizar el chat, debe incluir

tracingOptions: {
  tracingContext: context.active();
}

A continuación le mostramos un ejemplo:

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

Seguimiento de sus propias funciones

Open Telemetry proporciona startActiveSpan para instrumentar su propio código. A continuación le mostramos un ejemplo:

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

Solución de problemas

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, puede consultar los documentos del paquete de @azure/registrador.