Referencia de la API REST local de Foundry

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.

Request Body:

---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)
      Function name.
    • description (cadena)
      Function description.
    • 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.

Response body:

• 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:

Request body

  {
    "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": {}
  }

Response body

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

POST /v1/audio/transcriptions

Este punto de conexión transcribe los archivos de audio al texto. Es compatible con openAI Audio Transcriptions API.

Formato de solicitud:multipart/form-data

Request fields:

• file (archivo, obligatorio)
  Archivo de audio que se va a transcribir. Los formatos admitidos incluyen MP3, WAV, FLAC, OGG y WebM.
• model (cuerda, requerida)
  Identificador de modelo que se va a usar para la transcripción. Use el identificador devuelto al cargar un modelo de Susurro (por ejemplo, después de cargar whisper-tiny).
• language (cadena, opcional)
  Idioma del audio en formato ISO 639-1 (por ejemplo, "en"). Proporcionar esto mejora la precisión y la velocidad.
• temperature (número, opcional)
  Temperatura de muestreo entre 0 y 1. Los valores inferiores producen resultados más deterministas.
• response_format (cadena, opcional)
  Formato de la respuesta. Opciones: json (valor predeterminado), text, verbose_json.

Response body:

• text (cadena)
  Texto transcrito.

Example:

Request

curl -X POST http://localhost:<PORT>/v1/audio/transcriptions \
  -F "file=@recording.wav" \
  -F "model=<MODEL_ID>" \
  -F "language=en"

Response body

{
  "text": "This is the transcribed text from the audio file."
}

GET /openai/status

Obtiene la información de estado del servidor.

Response body:

• 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:

Response body

  {
    "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.

Response:

• 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.

Response:

• 200 OK
  Matriz de nombres de modelo como cadenas.

Example:

Response body

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

POST /openai/download

Descargue un modelo del catálogo en storage local.

Request Body:

• 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)
    Includes:
    • 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)
    El publisher 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.

Streaming Response:

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:

Request URI

POST /openai/download

Request body

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

Response stream

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

Final response

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

GET /openai/load/{name}

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

URI Parameters:

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

Query Parameters:

• 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.

Response:

• 200 OK
  Cuerpo de respuesta vacío

Example:

Request URI

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

GET /openai/unload/{name}

Descargar un modelo de la memoria.

URI Parameters:

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

Query Parameters:

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

Response:

• 200 Aceptar cuerpo de respuesta vacío

Example:

Request URI

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

GET /openai/unloadall

Descarga todos los modelos de la memoria.

Response:

• 200 OK
  Cuerpo de respuesta vacío

GET /openai/loadedmodels

Obtenga la lista de modelos cargados actualmente.

Response:

• 200 OK
  Matriz de nombres de modelo como cadenas.

Example:

Response body

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

GET /openai/getgpudevice

Obtenga el identificador de dispositivo de GPU actual.

Response:

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

GET /openai/setgpudevice/{deviceId}

Establezca el dispositivo GPU activo.

URI Parameters:

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

Response:

• 200 OK
  Cuerpo de respuesta vacío

Example:

• Request URI

  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.

Request Body:

• Content-Type: 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.

Response Body:

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

Example:

Request body

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

Response body

  {
    "tokenCount": 23
  }