Compartilhar via

Referência da API REST local do Foundry

Importante

  • A Fábrica Local está disponível na versão prévia. As visualizações públicas fornecem acesso antecipado a recursos que estão em implantação ativa.
  • Os recursos, abordagens e processos podem mudar ou ter seus recursos limitados antes da GA (disponibilidade geral).

Cuidado

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

POST /v1/chat/conclusões

Esse endpoint processa solicitações de finalização de chat.
Ele é totalmente compatível com a API de Conclusões de Chat do OpenAI.

Corpo da solicitação:

---Propriedades Padrão da 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. Precisa ser system, user ou assistant.
      • content (cadeia de caracteres)
        O texto da mensagem real.
  • 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 concentradas e consistentes.
  • top_p (número, opcional)
    Controla a diversidade de seleção de token de 0 a 1. Um valor de 0,1 significa que somente os tokens com as 10 maiores probabilidades% são considerados.
  • n (inteiro, opcional)
    Número de conclusões alternativas a serem geradas para cada mensagem de entrada.
  • stream (booliano, opcional)
    Quando verdadeiro, envia respostas parciais de mensagens como eventos enviados pelo servidor, terminando com uma mensagem data: [DONE].
  • stop (cadeia de caracteres 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 serem gerados. 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 ao penalizar tokens que já apareceram.
  • frequency_penalty (número, opcional)
    Valor entre -2.0 e 2.0. Os valores positivos desencorajam a repetição penalizando tokens com base em sua frequência no texto.
  • logit_bias (mapa, opcional)
    Ajusta a probabilidade de tokens específicos que aparecerem na conclusão.
  • user (cadeia de caracteres, opcional)
    Um identificador exclusivo para o usuário final que ajuda no monitoramento e na prevenção de abusos.
  • functions (array, 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 (cadeia de caracteres ou objeto, opcional)
    Controla como o modelo responde às chamadas de função.
    • Caso haja um objeto, pode incluir:
      • name (cadeia de caracteres, opcional)
        O nome da função a ser chamada.
      • arguments (objeto, opcional)
        Os argumentos a serem passados 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 serem mantidos para filtragem top-k.
  • random_seed (inteiro, opcional)
    Semente para geração de número aleatório reproduzível.
  • ep (cadeia de caracteres, opcional)
    Substitua o provedor para modelos ONNX. Dá suporte a: "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 a solicitação.

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 usado para conclusão.
  • choices (matriz)
    Lista de opções de conclusão, cada uma contendo:
    • index (Inteiro)
      O índice dessa escolha.
    • message (objeto)
      A mensagem gerada com:
      • role (cadeia de caracteres)
        Sempre use "assistant" para respostas.
      • content (cadeia de caracteres)
        O texto realmente gerado.
    • 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)
      Tokens no prompt.
    • completion_tokens (Inteiro)
      Tokens na conclusão.
    • total_tokens (Inteiro)
      Total de tokens usados.

Exemplo:

Corpo da 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 de status do servidor.

Corpo da resposta:

  • Endpoints (array de strings)
    Os pontos de extremidade de associação do servidor HTTP.
  • ModelDirPath (cadeia de caracteres)
    Diretório em que 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 /fábrica/listar

Obtenha uma lista dos modelos locais do Foundry 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 para o modelo, geralmente o mesmo que o nome.
    • providerType: o tipo de provedor que hospeda o modelo (por exemplo, AzureFoundry).
    • uri: o URI do recurso apontando para a localização do modelo no registro.
    • version: o número de 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 entre o usuário e o assistente.
    • publisher: a entidade ou organização que publicou o modelo.
    • task: a tarefa principal que o modelo foi projetado para executar (por exemplo, conclusão de chat).
    • runtime:
      • deviceType: o tipo de hardware no qual 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 abreviação para o modelo
    • supportsToolCalling: indica se o modelo dá suporte à funcionalidade de chamada de ferramentas.
    • license: o tipo de licença no qual o modelo é distribuído.
    • licenseDescription: uma descrição detalhada ou um link para os termos de licença.
    • parentModelUri: o URI do modelo pai do qual esse modelo é derivado.

GET /openai/modelos

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

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

Baixe um modelo do catálogo para o armazenamento local.

Observação

Downloads de modelos grandes podem levar muito tempo. Defina um tempo limite alto para essa solicitação para evitar o término antecipado.

Corpo da solicitação:

  • model (WorkspaceInferenceModel objeto)
    • Uri (cadeia de caracteres)
      O URI do modelo a ser baixado.
    • Name (cadeia de caracteres) O nome do modelo.
    • ProviderType (cadeia de caracteres, opcional)
      O tipo de provedor (por exemplo, "AzureFoundryLocal", "HuggingFace").
    • Path (cadeia de caracteres, opcional)
      Caminho remoto para os arquivos de modelo. Por exemplo, em um repositório de Detecção Facial, esse é o caminho para os arquivos de modelo.
    • PromptTemplate (Dictionary<string, string>opcional)
      Contém:
      • system (cadeia de caracteres, opcional)
        O modelo da mensagem do sistema.
      • user (cadeia de caracteres, opcional) O modelo para a mensagem do usuário.
      • assistant (cadeia de caracteres, opcional)
        O modelo para a resposta do assistente.
      • prompt (cadeia de caracteres, opcional)
        O modelo para a interação entre o usuário e o assistente.
    • Publisher (cadeia de caracteres, opcional)
      O editor do modelo.
  • token (cadeia de caracteres, opcional)
    Token de autenticação para modelos protegidos (GitHub ou Hugging Face).
  • progressToken (objeto, opcional)
    Somente para AITK. Token para acompanhar o progresso do download.
  • customDirPath (cadeia de caracteres, opcional)
    Diretório de download personalizado (usado para a CLI, não necessário para o AITK).
  • bufferSize (inteiro, opcional)
    Tamanho do buffer de download HTTP em KB. Nenhum efeito em modelos NIM ou Azure Foundry.
  • ignorePipeReport (booliano, opcional)
    Se true, força o progresso do relatório por meio do fluxo HTTP em vez de pipe. O padrão é para o false AITK e true para o 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 (booliano)
    Se o download foi concluído com êxito.
  • ErrorMessage (cadeia de caracteres, opcional)
    Detalhes do erro se o download falhou.

Exemplo:

URI de solicitação

POST /openai/download

Corpo da solicitação

Observe que o sufixo de 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/{name}

Carregue um modelo na memória para obter 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 (booliano, opcional)
    Se o modelo será descarregado automaticamente após o tempo ocioso. Usa true como padrão.
  • ttl (inteiro, opcional)
    Vida útil em segundos. Se for maior que 0, esse valor substituirá o unload parâmetro.
  • ep (cadeia de caracteres, opcional)
    Provedor de execução para executar esse modelo. Dá suporte a: "dml", , "cuda", "qnn", "cpu". "webgpu"
    Se não for especificado, usará as configurações de genai_config.json.

Resposta:

  • 200 OK
    Corpo de resposta vazio

Exemplo:

URI de solicitação

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

GET /openai/unload/{name}

Descarregue um modelo da memória.

Parâmetros de URI:

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

Parâmetros de consulta:

  • force (booliano, opcional) Se true, ignorará as configurações de TTL e descarregará imediatamente.

Resposta:

  • 200 OK Corpo de resposta vazio

Exemplo:

URI de solicitação

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 no momento.

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 a ID atual do dispositivo GPU.

Resposta:

  • 200 OK
    Um inteiro que representa a ID do dispositivo gpu atual.

GET /openai/setgpudevice/{deviceId}

Defina o dispositivo de GPU ativo.

Parâmetros de URI:

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

Resposta:

  • 200 OK
    Corpo de resposta vazio

Exemplo:

  • URI de solicitação 
    GET /openai/setgpudevice/1

POST /v1/chat/conclusões/tokenizer/codificar/contagem

Conta tokens para uma determinada solicitação de conclusão de chat sem executar inferência.

Corpo da solicitação:

  • Tipo de conteúdo: application/json
  • Objeto JSON em ChatCompletionCreateRequest formato com:
    • model (cadeia de caracteres)
      Modelo a ser usado para a 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 da 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
  }
  • Last updated on