Referência da API REST local do Foundry

Importante

O Foundry Local está disponível em pré-visualização. As versões de visualização pública fornecem acesso antecipado aos recursos que estão em implantação ativa.
Recursos, abordagens e processos podem mudar ou ter recursos limitados, antes da Disponibilidade Geral (GA).

Atenção

Esta API refere-se à API REST disponível na CLI Local da Foundry. Esta API está em desenvolvimento ativo e pode incluir alterações sem aviso prévio. É altamente recomendável monitorar o changelog antes de criar aplicativos de produção.

POST /v1/chat/completamentos

Este ponto de acesso processa pedidos de conclusão de chat.
É totalmente compatível com a API OpenAI Chat Completions.

Órgão do pedido:

---Propriedades padrão do OpenAI---

model (cadeia de caracteres)
O modelo específico a ser usado para conclusão.
messages (matriz)
O histórico de conversas como uma lista de mensagens.
- Cada mensagem requer:
  - role (cadeia de caracteres)
    A função do remetente da mensagem. Deve ser system, user, ou assistant.
  - content (cadeia de caracteres)
    O texto real da mensagem.
temperature (número, opcional)
Controla a aleatoriedade, variando de 0 a 2. Valores mais altos (0,8) criam saídas variadas, enquanto valores mais baixos (0,2) criam saídas focadas e consistentes.
top_p (número, opcional)
Controla a diversidade de seleção de tokens de 0 a 1. Um valor de 0,1 significa que apenas os tokens no top 10% probabilidade são considerados.
n (inteiro, opcional)
Número de completações alternativas a gerar para cada mensagem de entrada.
stream (booleano, opcional)
Quando verdadeiro, envia respostas parciais de mensagens como eventos enviados pelo servidor, terminando com uma data: [DONE] mensagem.
stop (string ou matriz, opcional)
Até 4 sequências que farão com que o modelo pare de gerar mais tokens.
max_tokens (inteiro, opcional)
Número máximo de tokens a gerar. Para modelos mais recentes, use max_completion_tokens em vez disso.
max_completion_tokens (inteiro, opcional)
Número máximo de tokens que o modelo pode gerar, incluindo tokens de saída e raciocínio visíveis.
presence_penalty (número, opcional)
Valor entre -2,0 e 2,0. Valores positivos incentivam o modelo a discutir novos tópicos, penalizando tokens que já apareceram.
frequency_penalty (número, opcional)
Valor entre -2,0 e 2,0. Os valores positivos desencorajam a repetição ao penalizar as fichas com base na sua frequência no texto.
logit_bias (mapa, opcional)
Ajusta a probabilidade de tokens específicos aparecerem na conclusão.
user (string, opcional)
Um identificador exclusivo para o seu utilizador final que ajuda na monitorização e prevenção de abusos.
functions (matriz, opcional)
Funções disponíveis para as quais o modelo pode gerar entradas JSON.
- Cada função deve incluir:
  - name (cadeia de caracteres)
    Nome da função.
  - description (cadeia de caracteres)
    Descrição da função.
  - parameters (objeto)
    Parâmetros de função descritos como um objeto de esquema JSON.
function_call (string ou objeto, opcional)
Controla como o modelo responde a chamadas de função.
- Se objeto, pode incluir:
  - name (string, opcional)
    O nome da função a ser chamada.
  - arguments (objeto, opcional)
    Os argumentos a passar para a função.
metadata (objeto, opcional)
Um dicionário de pares chave-valor de metadados.
top_k (número, opcional)
O número de tokens de vocabulário de maior probabilidade a manter na filtragem top-k.
random_seed (inteiro, opcional)
Semente para geração de números aleatórios reprodutíveis.
ep (string, opcional)
Substitua o provedor de modelos ONNX. Apoios: "dml", "cuda", , "qnn", "cpu". "webgpu"
ttl (inteiro, opcional)
Tempo de vida em segundos para o modelo na memória.
tools (objeto, opcional)
Ferramentas calculadas para o pedido.

Corpo da resposta:

id (cadeia de caracteres)
Identificador exclusivo para a conclusão do chat.
object (cadeia de caracteres)
O tipo de objeto, sempre "chat.completion".
created (inteiro)
Carimbo de data/hora de criação em segundos de época.
model (cadeia de caracteres)
O modelo utilizado para a conclusão.
choices (matriz)
Lista de opções de preenchimento, cada uma contendo:
- index (inteiro)
  O índice desta escolha.
- message (objeto)
  A mensagem gerada com:
  - role (cadeia de caracteres)
    Sempre utilize "assistant" para respostas.
  - content (cadeia de caracteres)
    O texto gerado realmente.
- finish_reason (cadeia de caracteres)
  Por que a geração parou (por exemplo, "stop", "length", "function_call").
usage (objeto)
Estatísticas de uso de token:
- prompt_tokens (inteiro)
  Os tokens no prompt.
- completion_tokens (inteiro)
  Tokens na conclusão.
- total_tokens (inteiro)
  Total de tokens usados.

Exemplo:

Corpo de solicitação

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

Corpo da resposta

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

Obtenha informações sobre o status do servidor.

Corpo da resposta:

Endpoints (array de strings)
Os endpoints de associação do servidor HTTP.
ModelDirPath (cadeia de caracteres)
Diretório onde os modelos locais são armazenados.
PipeName (cadeia de caracteres)
O nome atual do servidor NamedPipe.

Exemplo:

Corpo da resposta

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

GET /fundição/lista

Obtenha uma lista dos modelos Foundry Local disponíveis no catálogo.

Resposta:

models (matriz)
Matriz de objetos de modelo. Cada modelo inclui:
- name: O identificador exclusivo do modelo.
- displayName: Um nome legível por humanos para o modelo, muitas vezes o mesmo que o nome.
- providerType: O tipo de provedor que hospeda o modelo (por exemplo, AzureFoundry).
- uri: A URI do recurso que aponta para a localização do modelo no registo.
- version: O número da versão do modelo.
- modelType: O formato ou tipo do modelo (por exemplo, ONNX).
- promptTemplate:
  - assistant: O modelo para a resposta do assistente.
  - prompt: O modelo para a interação usuário-assistente.
- publisher: A entidade ou organização que publicou o modelo.
- task: A tarefa principal para a qual o modelo foi projetado (por exemplo, conclusão do bate-papo).
- runtime:
  - deviceType: O tipo de hardware em que o modelo foi projetado para ser executado (por exemplo, CPU).
  - executionProvider: O provedor de execução usado para executar o modelo.
- fileSizeMb: O tamanho do arquivo de modelo em megabytes.
- modelSettings:
  - parameters: Uma lista de parâmetros configuráveis para o modelo.
- alias: Um nome alternativo ou uma abreviatura para o modelo
- supportsToolCalling: Indica se o modelo suporta a funcionalidade de chamada de ferramentas.
- license: O tipo de licença sob o qual o modelo é distribuído.
- licenseDescription: Uma descrição detalhada ou link para os termos da licença.
- parentModelUri: O URI do modelo pai do qual este modelo é derivado.

GET /openai/modelos

Obtenha uma lista de modelos em cache, incluindo modelos locais e externos registados.

Resposta:

200 OK
Uma matriz de nomes de modelo como cadeias de caracteres.

Exemplo:

Corpo da resposta

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

POST /openai/download

Descarregue um modelo do catálogo para armazenamento local.

Observação

Downloads de grandes modelos podem demorar muito tempo. Defina um tempo limite elevado para este pedido para evitar a rescisão antecipada.

Órgão do pedido:

model(WorkspaceInferenceModel objeto)
- Uri (cadeia de caracteres)
  O URI do modelo a ser baixado.
- Name (string) O nome do modelo.
- ProviderType (string, opcional)
  O tipo de fornecedor (por exemplo, "AzureFoundryLocal", "HuggingFace").
- Path (string, opcional)
  Caminho remoto para os ficheiros de modelo. Por exemplo, num repositório Hugging Face, este é o caminho para os ficheiros do modelo.
- PromptTemplate (Dictionary<string, string>, opcional)
  Inclui:
  - system (string, opcional)
    O modelo para a mensagem do sistema.
  - user (string, opcional) O modelo para a mensagem do usuário.
  - assistant (string, opcional)
    O modelo para a resposta do assistente.
  - prompt (string, opcional)
    O modelo para a interação usuário-assistente.
- Publisher (string, opcional)
  A editora do modelo.
token (string, opcional)
Token de autenticação para modelos protegidos (GitHub ou Hugging Face).
progressToken (objeto, opcional)
Apenas para AITK. Token para acompanhar o progresso do download.
customDirPath (string, opcional)
Diretório de download personalizado (usado para CLI, não necessário para AITK).
bufferSize (inteiro, opcional)
Tamanho do buffer de download HTTP em KB. Nenhum efeito nos modelos NIM ou Azure Foundry.
ignorePipeReport (booleano, opcional)
Se true, obriga a utilização de fluxo HTTP para o relatório de progresso em vez de usar pipe. Por defeito, é false para AITK e true para a Foundry Local.

Resposta de streaming:

Durante o download, o servidor transmite atualizações de progresso no formato:

("file name", percentage_complete)

Corpo da resposta final:

Success (booleano)
Se o download foi concluído com êxito.
ErrorMessage (string, opcional)
Detalhes do erro se o download falhar.

Exemplo:

Solicitar URI

POST /openai/download

Corpo de solicitação

Note que o sufixo da versão deve ser fornecido no nome do 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|>"
    }
  }
}

Fluxo de resposta

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

Resposta final

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

GET /openai/load/{nome}

Carregue um modelo na memória para uma inferência mais rápida.

Parâmetros de URI:

name (cadeia de caracteres)
O nome do modelo a ser carregado.

Parâmetros de consulta:

unload (booleano, opcional)
Se o modelo deve ser descarregado automaticamente após o tempo ocioso. O padrão é true.
ttl (inteiro, opcional)
Tempo para viver em segundos. Se for maior que 0, esse valor substituirá o unload parâmetro.
ep (string, opcional)
Provedor de execução para executar este modelo. Apoios: "dml", "cuda", , "qnn", "cpu". "webgpu"
Se não for especificado, usa as configurações de genai_config.json.

Resposta:

200 OK
Corpo de resposta vazio

Exemplo:

Solicitar URI

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

GET /openai/unload/{name}

Descarrega um modelo da memória.

Parâmetros de URI:

name (corda) O nome do modelo a vender.

Parâmetros de consulta:

force (booleano, opcional) Se true, ignora as definições TTL e descarrega imediatamente.

Resposta:

200 OK Corpo de resposta vazio

Exemplo:

Solicitar URI

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

GET /openai/unloadall

Descarrega todos os modelos da memória.

Resposta:

200 OK
Corpo de resposta vazio

GET /openai/loadedmodels

Obtenha a lista de modelos carregados atualmente.

Resposta:

200 OK
Uma matriz de nomes de modelo como cadeias de caracteres.

Exemplo:

Corpo da resposta

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

GET /openai/getgpudevice

Obtenha o ID atual do dispositivo GPU.

Resposta:

200 OK
Um inteiro que representa o ID do dispositivo GPU atual.

GET /openai/setgpudevice/{deviceId}

Defina o dispositivo GPU ativo.

Parâmetros de URI:

deviceId (inteiro)
O ID do dispositivo GPU a ser usado.

Resposta:

200 OK
Corpo de resposta vazio

Exemplo:

Solicitar URI
```
GET /openai/setgpudevice/1
```

POST /v1/chat/conclusão/tokenizador/codificar/contagem

Conta tokens para uma determinada solicitação de conclusão de bate-papo sem realizar inferência.

Órgão do pedido:

Tipo de conteúdo: application/json
Objeto JSON em ChatCompletionCreateRequest formato com:
- model (cadeia de caracteres)
  Modelo a utilizar para tokenização.
- messages (matriz)
  Matriz de objetos de mensagem com role e content.

Corpo da resposta:

Tipo de conteúdo: application/json
Objeto JSON com contagem de tokens:
- tokenCount (inteiro)
  Número de tokens na solicitação.

Exemplo:

Corpo de solicitação

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

Corpo da resposta

  {
    "tokenCount": 23
  }

Feedback

Esta página foi útil?

Last updated on 2026-02-28

Partilhar via

Referência da API REST local do Foundry

POST /v1/chat/completamentos

GET /openai/status

GET /fundição/lista

GET /openai/modelos

POST /openai/download

GET /openai/load/{nome}

GET /openai/unload/{name}

GET /openai/unloadall

GET /openai/loadedmodels

GET /openai/getgpudevice

GET /openai/setgpudevice/{deviceId}

POST /v1/chat/conclusão/tokenizador/codificar/contagem

Feedback

Recursos adicionais