Compartir a través de

Referencia de la API REST local de Foundry

Importante

  • Foundry Local está disponible en versión preliminar. Las versiones preliminares públicas proporcionan acceso anticipado a las características que se encuentran en la implementación activa.
  • Las características, los enfoques y los procesos pueden cambiar o tener funcionalidades limitadas, antes de la disponibilidad general (GA).

Precaución

Esta API hace referencia a la API REST disponible en la CLI local de Foundry. Esta API está en desarrollo activo y puede incluir cambios importantes sin previo aviso. Se recomienda encarecidamente consultar el registro de cambios antes de desarrollar aplicaciones de producción.

POST /v1/chat/completions

Este punto de conexión procesa las solicitudes de finalización del chat.
Es totalmente compatible con la API de finalizaciones de chat de OpenAI.

Cuerpo de la solicitud:

---Propiedades Estándar de OpenAI---

  • model (cadena)
    Modelo específico que se va a usar para la finalización.
  • messages (matriz)
    El historial de conversaciones como una lista de mensajes.
    • Cada mensaje requiere:
      • role (cadena)
        Rol del remitente del mensaje. Debe ser system, user o assistant.
      • content (cadena)
        Texto real del mensaje.
  • temperature (número, opcional)
    Controla la aleatoriedad, que va de 0 a 2. Los valores más altos (0,8) crean salidas variadas, mientras que los valores inferiores (0,2) crean salidas centradas y coherentes.
  • top_p (número, opcional)
    Controla la diversidad de selección de tokens de 0 a 1. Un valor de 0,1 significa que solo se consideran los tokens con las 10 probabilidades más altas%.
  • n (entero, opcional)
    Número de finalizaciones alternativas que se van a generar para cada mensaje de entrada.
  • stream (booleano, opcional)
    Cuando es true, envía respuestas parciales de mensajes como eventos enviados por el servidor, finalizando con un data: [DONE] mensaje.
  • stop (cadena o matriz, opcional)
    Hasta 4 secuencias que harán que el modelo deje de generar tokens adicionales.
  • max_tokens (entero, opcional)
    Número máximo de tokens a generar. En el caso de los modelos más recientes, use max_completion_tokens en su lugar.
  • max_completion_tokens (entero, opcional)
    Número máximo de tokens que puede generar el modelo, incluidos los tokens de salida y razonamiento visibles.
  • presence_penalty (número, opcional)
    Valor entre -2.0 y 2.0. Los valores positivos animan al modelo a analizar nuevos temas penalizando los tokens que ya han aparecido.
  • frequency_penalty (número, opcional)
    Valor entre -2.0 y 2.0. Los valores positivos desaconsejan la repetición penalizando los tokens en función de su frecuencia en el texto.
  • logit_bias (mapa, opcional)
    Ajusta la probabilidad de que aparezcan tokens específicos en la finalización.
  • user (cadena, opcional)
    Un identificador único para el usuario final que ayuda con la supervisión y la prevención de abusos.
  • functions (matriz, opcional)
    Funciones disponibles para las que el modelo puede generar entradas JSON.
    • Cada función debe incluir:
      • name (cadena)
        Nombre de la función.
      • description (cadena)
        Descripción de la función.
      • parameters (objeto)
        Parámetros de función descritos como un objeto de esquema JSON.
  • function_call (cadena o objeto, opcional)
    Controla cómo responde el modelo a las llamadas de función.
    • Si es un objeto, puede incluir:
      • name (cadena, opcional)
        El nombre de la función que se va a llamar.
      • arguments (objeto, opcional)
        Argumentos que se van a pasar a la función.
  • metadata (objeto, opcional)
    Diccionario de pares clave-valor de metadatos.
  • top_k (número, opcional)
    Número de tokens de vocabulario de probabilidad más alta que se mantendrán para el filtrado de k superior.
  • random_seed (entero, opcional)
    Semilla para la generación de números aleatorios reproducibles.
  • ep (cadena, opcional)
    Sobrescriba el proveedor para los modelos ONNX. Admite: "dml", "cuda", "qnn", "cpu", "webgpu".
  • ttl (entero, opcional)
    Período de vida en segundos para el modelo en memoria.
  • tools (objeto, opcional)
    Herramientas calculadas para la solicitud.

Cuerpo de la respuesta:

  • id (cadena)
    Identificador único para la finalización del chat.
  • object (cadena)
    Tipo de objeto, siempre "chat.completion".
  • created (entero)
    Marca de tiempo de creación en segundos de época.
  • model (cadena)
    Modelo usado para la finalización.
  • choices (matriz)
    Lista de opciones de finalización, cada una que contiene:
    • index (entero)
      Índice de esta elección.
    • message (objeto)
      Mensaje generado con:
      • role (cadena)
        Siempre "assistant" para las respuestas.
      • content (cadena)
        Texto generado real.
    • finish_reason (cadena)
      Por qué se detuvo la generación (por ejemplo, "stop", "length", "function_call").
  • usage (objeto)
    Estadísticas de uso de tokens:
    • prompt_tokens (entero)
      Tokens en el símbolo del sistema.
    • completion_tokens (entero)
      Tokens en la finalización.
    • total_tokens (entero)
      Número total de tokens usados.

Example:

Cuerpo de la solicitud

  {
    "model": "qwen2.5-0.5b-instruct-generic-cpu",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "temperature": 0.7,
    "top_p": 1,
    "n": 1,
    "stream": false,
    "stop": null,
    "max_tokens": 100,
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "logit_bias": {},
    "user": "user_id_123",
    "functions": [],
    "function_call": null,
    "metadata": {}
  }

Cuerpo de respuesta

  {
    "id": "chatcmpl-1234567890",
    "object": "chat.completion",
    "created": 1677851234,
    "model": "qwen2.5-0.5b-instruct-generic-cpu",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "I'm doing well, thank you! How can I assist you today?"
        },
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 10,
      "completion_tokens": 20,
      "total_tokens": 30
    }
  }

GET /openai/status

Obtiene la información de estado del servidor.

Cuerpo de la respuesta:

  • Endpoints (matriz de cadenas)
    Puntos de conexión de enlace de servidor HTTP.
  • ModelDirPath (cadena)
    Directorio donde se almacenan los modelos locales.
  • PipeName (cadena)
    Nombre actual del servidor NamedPipe.

Example:

Cuerpo de respuesta

  {
    "Endpoints": ["http://localhost:5272"],
    "ModelDirPath": "/path/to/models",
    "PipeName": "inference_agent"
  }

GET /foundry/list

Obtenga una lista de los modelos locales de Foundry disponibles en el catálogo.

Respuesta:

  • models (matriz)
    Matriz de objetos de modelo. Cada modelo incluye:
    • name: identificador único del modelo.
    • displayName: Un nombre legible para el modelo, a menudo igual que el nombre.
    • providerType: el tipo de proveedor que hospeda el modelo (por ejemplo, AzureFoundry).
    • uri: el URI del recurso que apunta a la ubicación del modelo en el Registro.
    • version: número de versión del modelo.
    • modelType: formato o tipo del modelo (por ejemplo, ONNX).
    • promptTemplate:
      • assistant: plantilla para la respuesta del asistente.
      • prompt: plantilla de interacción entre el usuario y el asistente.
    • publisher: entidad u organización que publicó el modelo.
    • task: la tarea principal que el modelo está diseñado para realizar (por ejemplo, finalización del chat).
    • runtime:
      • deviceType: el tipo de hardware que el modelo está diseñado para ejecutarse (por ejemplo, CPU).
      • executionProvider: el proveedor de ejecución usado para ejecutar el modelo.
    • fileSizeMb: tamaño del archivo de modelo en megabytes.
    • modelSettings:
      • parameters: una lista de parámetros configurables para el modelo.
    • alias: nombre alternativo o abreviatura para el modelo
    • supportsToolCalling: indica si el modelo admite la funcionalidad de llamada a herramientas.
    • license: tipo de licencia con el que se distribuye el modelo.
    • licenseDescription: una descripción detallada o un vínculo a los términos de licencia.
    • parentModelUri: el URI del modelo primario desde el que se deriva este modelo.

GET /openai/models

Obtenga una lista de modelos almacenados en caché, incluidos los modelos externos locales y registrados.

Respuesta:

  • 200 Ok
    Matriz de nombres de modelo como cadenas.

Example:

Cuerpo de respuesta

  ["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

POST /openai/download

Descargue un modelo del catálogo en el almacenamiento local.

Nota:

Las descargas de modelos grandes pueden tardar mucho tiempo. Establezca un tiempo de espera elevado para esta solicitud para evitar la terminación anticipada.

Cuerpo de la solicitud:

  • model (WorkspaceInferenceModel objeto)
    • Uri (cadena)
      URI del modelo para descargar.
    • Name Nombre del modelo.
    • ProviderType (cadena, opcional)
      Tipo de proveedor (por ejemplo, "AzureFoundryLocal", "HuggingFace").
    • Path (cadena, opcional)
      Ruta de acceso remota a los archivos de modelo. Por ejemplo, en un repositorio de Hugging Face, esta es la ruta de acceso a los archivos de modelo.
    • PromptTemplate (Dictionary<string, string>, opcional)
      Incluye:
      • system (cadena, opcional)
        Plantilla del mensaje del sistema.
      • user (cadena, opcional) Plantilla del mensaje del usuario.
      • assistant (cadena, opcional)
        Plantilla para la respuesta del asistente.
      • prompt (cadena, opcional)
        Plantilla para la interacción entre el usuario y el asistente.
    • Publisher (cadena, opcional)
      Publicador del modelo.
  • token (cadena, opcional)
    Token de autenticación para modelos protegidos (GitHub o Hugging Face).
  • progressToken (objeto, opcional)
    Solo para AITK. Token para realizar un seguimiento del progreso de la descarga.
  • customDirPath (cadena, opcional)
    Directorio de descarga personalizado (usado para la CLI, no necesario para AITK).
  • bufferSize (entero, opcional)
    Tamaño del búfer de descarga HTTP en KB. No hay ningún efecto en los modelos NIM o Azure Foundry.
  • ignorePipeReport (booleano, opcional)
    Si es true, fuerza los informes de progreso a través de la secuencia HTTP en lugar de la canalización. El valor predeterminado es false para AITK y true para Foundry Local.

Respuesta de streaming:

Durante la descarga, el servidor transmite las actualizaciones de progreso en el formato:

("file name", percentage_complete)

Cuerpo final de la respuesta:

  • Success (booleano)
    Si la descarga se completó correctamente.
  • ErrorMessage (cadena, opcional)
    Detalles del error si se produjo un error en la descarga.

Example:

Solicitud de URI

POST /openai/download

Cuerpo de la solicitud

Tenga en cuenta que el sufijo de versión debe proporcionarse en el nombre del modelo.

{
  "model": {
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu:4",
    "Publisher": "",
    "PromptTemplate": {
      "system": "<|system|>{Content}<|end|>",
      "user": "<|user|>{Content}<|end|>",
      "assistant": "<|assistant|>{Content}<|end|>",
      "prompt": "<|user|>{Content}<|end|><|assistant|>"
    }
  }
}

Flujo de respuesta

  ("genai_config.json", 0.01)
  ("genai_config.json", 0.2)
  ("model.onnx.data", 0.5)
  ("model.onnx.data", 0.78)
  ...
  ("", 1)

Respuesta final

  {
    "Success": true,
    "ErrorMessage": null
  }

GET /openai/load/{name}

Cargue un modelo en memoria para obtener una inferencia más rápida.

Parámetros de URI:

  • name (cadena)
    Nombre del modelo que se va a cargar.

Parámetros de consulta:

  • unload (booleano, opcional)
    Si se descarga automáticamente el modelo después del tiempo de inactividad. Tiene como valor predeterminado true.
  • ttl (entero, opcional)
    Período de vida en segundos. Si es mayor que 0, este valor invalida el unload parámetro .
  • ep (cadena, opcional)
    Proveedor de ejecución para ejecutar este modelo. Admite: "dml", "cuda", "qnn", "cpu", "webgpu".
    Si no se especifica, usa la configuración de genai_config.json.

Respuesta:

  • 200 Ok
    Cuerpo de respuesta vacío

Example:

Solicitud de URI

  GET /openai/load/Phi-4-mini-instruct-generic-cpu?ttl=3600&ep=dml

GET /openai/unload/{name}

Descargar un modelo de la memoria.

Parámetros de URI:

  • name (cadena) Nombre del modelo que se va a descargar.

Parámetros de consulta:

  • force (booleano, opcional) Si truees , omite la configuración de TTL y descarga inmediatamente.

Respuesta:

  • 200 Aceptar cuerpo de respuesta vacío

Example:

Solicitud de URI

GET /openai/unload/Phi-4-mini-instruct-generic-cpu?force=true

GET /openai/unloadall

Descarga todos los modelos de la memoria.

Respuesta:

  • 200 Ok
    Cuerpo de respuesta vacío

GET /openai/loadedmodels

Obtenga la lista de modelos cargados actualmente.

Respuesta:

  • 200 Ok
    Matriz de nombres de modelo como cadenas.

Example:

Cuerpo de respuesta

["Phi-4-mini-instruct-generic-cpu", "phi-3.5-mini-instruct-generic-cpu"]

GET /openai/getgpudevice

Obtenga el identificador de dispositivo de GPU actual.

Respuesta:

  • 200 Ok
    Entero que representa el identificador de dispositivo de GPU actual.

GET /openai/setgpudevice/{deviceId}

Establezca el dispositivo GPU activo.

Parámetros de URI:

  • deviceId (entero)
    Identificador de dispositivo de GPU a usar.

Respuesta:

  • 200 Ok
    Cuerpo de respuesta vacío

Example:

  • URI de solicitud
    GET /openai/setgpudevice/1

POST /v1/chat/completions/tokenizer/encode/count

Cuenta los tokens de una solicitud de finalización de chat determinada sin realizar la inferencia.

Cuerpo de la solicitud:

  • Tipo de contenido: application/json
  • Objeto JSON en ChatCompletionCreateRequest formato con:
    • model (cadena)
      Modelo que se va a usar para la tokenización.
    • messages (matriz)
      Matriz de objetos de mensaje con role y content.

Cuerpo de la respuesta:

  • Tipo de contenido: application/json
  • Objeto JSON con recuento de tokens:
    • tokenCount (entero)
      Número de tokens en la solicitud.

Example:

Cuerpo de la solicitud

  {
    "messages": [
      {
        "role": "system",
        "content": "This is a system message"
      },
      {
        "role": "user",
        "content": "Hello, what is Microsoft?"
      }
    ],
    "model": "Phi-4-mini-instruct-cuda-gpu"
  }

Cuerpo de respuesta

  {
    "tokenCount": 23
  }
  • Last updated on