Foundry Local REST API 参考

重要

• Foundry Local 以预览版形式提供。 通过公共预览版，可以提前访问正处于开发状态的功能。
• 正式发布 (GA) 之前，功能、方法和流程可能会发生更改或功能受限。

谨慎

此 API 是指 Foundry 本地 CLI 中提供的 REST API。 此 API 正在积极开发中，可能会包含不通知的重大变更。 强烈建议在生成生产应用程序之前监视更改日志。

POST /v1/chat/completions

此终结点处理聊天完成请求。
它与 OpenAI 聊天完成 API 完全兼容。

请求正文：

---Standard OpenAI 属性---

• model（字符串）
  用于完成的具体模型。
• messages （数组）
  将对话历史记录显示为消息列表。
  • 每条消息都需要：
    • role（字符串）
      邮件发件人的角色。 必须为 system、user 或 assistant。
    • content（字符串）
      实际消息文本。
• temperature （数字，可选）
  控制随机性，范围为 0 到 2。 较高的值 （0.8） 会创建不同的输出，而较低值 （0.2） 则创建聚焦的一致输出。
• top_p （数字，可选）
  控制从 0 到 1 的令牌选择多样性。 值为 0.1 表示仅考虑概率排名前 10% 的标记。
• n （整数，可选）
  为每个输入消息生成的备选补全数量。
• stream （布尔值，可选）
  如果为 true，则发送部分消息响应作为服务器发送的事件，以消息 data: [DONE] 结尾。
• stop （字符串或数组，可选）
  最多 4 个序列将导致模型停止生成更多令牌。
• max_tokens （整数，可选）
  要生成的标记的最大数目。 对于较新的模型，请改用 max_completion_tokens 。
• max_completion_tokens （整数，可选）
  模型可以生成的最大令牌数，包括可见输出和推理令牌。
• presence_penalty （数字，可选）
  介于 -2.0 和 2.0 之间的值。 正值通过惩罚已经出现的标记来鼓励模型讨论新主题。
• frequency_penalty （数字，可选）
  介于 -2.0 和 2.0 之间的值。 正值根据标记在文本中出现的频率对其进行惩罚，从而阻止重复。
• logit_bias （地图，可选）
  调整特定标记在补全中出现的概率。
• user （字符串，可选）
  最终用户的唯一标识符，可帮助监视和滥用预防。
• functions （数组，可选）
  可用函数，模型可以为其生成 JSON 输入。
  • 每个函数必须包括：
    • name（字符串）
      函数名称。
    • description（字符串）
      函数说明。
    • parameters （对象）
      描述为 JSON 架构对象的函数参数。
• function_call （字符串或对象，可选）
  控制模型如何响应函数调用。
  • 如果是对象，可以包括：
    • name （字符串，可选）
      要调用的函数名称。
    • arguments （对象，可选）
      要传递给函数的参数。
• metadata （对象，可选）
  元数据键值对的字典。
• top_k （数字，可选）
  为 top-k-filtering 保留的最高概率词汇标记数。
• random_seed （整数，可选）
  可重现随机数生成的种子。
• ep （字符串，可选）
  覆盖 ONNX 模型的提供程序。 支持："dml"、、"cuda""qnn"、"cpu"、 "webgpu"。
• ttl （整数，可选）
  内存中模型的生存时间（以秒为单位）。
• tools （对象，可选）
  根据请求计算的工具。

响应正文：

• id（字符串）
  聊天补全的唯一标识符。
• object（字符串）
  对象类型始终为"chat.completion"。
• created （整数）
  创建时间戳（以纪元秒为单位）。
• model（字符串）
  用于补全的模型。
• choices （数组）
  完成选项的列表，每个选项都包含：
  • index （整数）
    此选项的索引。
  • message （对象）
    生成的消息，其中包含：
    • role（字符串）
      对于响应始终为 "assistant"。
    • content（字符串）
      实际生成的文本。
  • finish_reason（字符串）
    为什么生成停止（例如，"stop"、"length"、"function_call"）。
• usage （对象）
  令牌使用情况统计信息：
  • prompt_tokens （整数）
    提示中的标记。
  • completion_tokens （整数）
    补全中的标记。
  • total_tokens （整数）
    使用的令牌总数。

示例：

请求主体

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

响应体

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

获取服务器状态信息。

响应正文：

• Endpoints （字符串数组）
  HTTP 服务器绑定终结点。
• ModelDirPath（字符串）
  存储本地模型的目录。
• PipeName（字符串）
  当前 NamedPipe 服务器名称。

示例：

响应体

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

GET /foundry/list

获取目录中可用的 Foundry Local 模型的列表。

响应：

• models （数组）
  模型对象的数组。 每个模型包括：
  • name：模型的唯一标识符。
  • displayName：模型的可读名称，通常与名称相同。
  • providerType：托管模型的提供程序类型（例如 AzureFoundry）。
  • uri：指向模型在注册表中的位置的资源 URI。
  • version：模型的版本号。
  • modelType：模型的格式或类型（例如 ONNX）。
  • promptTemplate：
    • assistant：助手响应的模板。
    • prompt：用户助理交互的模板。
  • publisher：发布模型的实体或组织。
  • task：模型旨在执行的主要任务（例如聊天完成）。
  • runtime：
    • deviceType：模型设计用于运行的硬件类型（例如 CPU）。
    • executionProvider：用于运行模型的执行提供程序。
  • fileSizeMb：模型文件的大小（以 MB 为单位）。
  • modelSettings：
    • parameters：模型的可配置参数列表。
  • alias：模型的可选名称或简写
  • supportsToolCalling：指示模型是否支持工具调用功能。
  • license：分配模型的许可证类型。
  • licenseDescription：详细说明或指向许可条款的链接。
  • parentModelUri：从中派生此模型的父模型的 URI。

GET /openai/models

获取缓存模型的列表，包括本地模型和已注册的外部模型。

响应：

• 200 正常
  字符串形式的模型名称数组。

示例：

响应体

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

POST /openai/download

将模型从目录下载到本地存储。

注释

大型模型下载可能需要很长时间。 为此请求设置高超时，以避免提前终止。

请求正文：

• model （WorkspaceInferenceModel 对象）
  • Uri（字符串）
    要下载的模型 URI。
  • Name （字符串）模型名称。
  • ProviderType （字符串，可选）
    提供程序类型（例如，"AzureFoundryLocal""HuggingFace"）。
  • Path （字符串，可选）
    模型文件的远程路径。 例如，在拥抱人脸存储库中，这是模型文件的路径。
  • PromptTemplate （Dictionary<string, string>可选）
    包括：
    • system （字符串，可选）
      系统消息的模板。
    • user （字符串，可选）用户消息的模板。
    • assistant （字符串，可选）
      助手响应的模板。
    • prompt （字符串，可选）
      用户助理交互的模板。
  • Publisher （字符串，可选）
    模型的发布者。
• token （字符串，可选）
  受保护模型的身份验证令牌（GitHub 或 Hugging Face）。
• progressToken （对象，可选）
  仅适用于 AITK。 用于跟踪下载进度的令牌。
• customDirPath （字符串，可选）
  自定义下载目录（用于 CLI，AITK 不需要）。
• bufferSize （整数，可选）
  HTTP 下载缓冲区大小（以 KB 为单位）。 对 NIM 或 Azure Foundry 模型没有影响。
• ignorePipeReport （布尔值，可选）
  如果 true，则强制通过 HTTP 流而不是管道进行进度报告。 对于 AITK，默认为 false；对于 Foundry Local，默认为 true。

流式处理响应：

在下载期间，服务器以以下格式流式传输进度更新：

("file name", percentage_complete)

最终响应正文：

• Success（布尔值）
  下载是否已成功完成。
• ErrorMessage （字符串，可选）
  下载失败时显示的错误详细信息。

示例：

请求 URI

POST /openai/download

请求主体

请注意，必须在模型名称中提供版本后缀。

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

响应流

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

最终响应

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

GET /openai/load/{name}

将模型加载到内存中以加快推理速度。

URI 参数：

• name（字符串）
  要加载的模型名称。

查询参数：

• unload （布尔值，可选）
  是否在空闲时间后自动卸载模型。 默认为 true。
• ttl （整数，可选）
  生存时间（以秒为单位）。 如果大于 0，则此值将覆盖unload参数。
• ep （字符串，可选）
  用于运行此模型的执行提供程序。 支持："dml"、、"cuda""qnn"、"cpu"、 "webgpu"。
  如果未指定，则使用来自 genai_config.json.. 的设置。

响应：

• 200 正常
  空响应正文

示例：

请求 URI

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

GET /openai/unload/{name}

从内存中卸载模型。

URI 参数：

• name（字符串）
  要卸载的模型名称。

查询参数：

• force （布尔值，可选）
  如果 true，则忽略 TTL 设置并立即卸载。

响应：

• 200 正常
  空响应正文

示例：

请求 URI

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

GET /openai/unloadall

从内存中卸载所有模型。

响应：

• 200 正常
  空响应正文

GET /openai/loadedmodels

获取当前加载的模型的列表。

响应：

• 200 正常
  字符串形式的模型名称数组。

示例：

响应体

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

GET /openai/getgpudevice

获取当前的 GPU 设备 ID。

响应：

• 200 正常
  表示当前 GPU 设备 ID 的整数。

GET /openai/setgpudevice/{deviceId}

设置活动 GPU 设备。

URI 参数：

• deviceId （整数）
  要使用的 GPU 设备 ID。

响应：

• 200 正常
  空响应正文

示例：

• 请求 URI

  GET /openai/setgpudevice/1
  

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

在不执行推理的情况下，为给定的聊天完成请求计算令牌数量。

请求正文：

• Content-Type：application/json
• 格式为 ChatCompletionCreateRequest 的 JSON 对象：
  • model（字符串）
    用于标记化的模型。
  • messages （数组）
    包含 role 和 content. 的消息对象的数组。

响应正文：

• Content-Type：application/json
• 包含令牌计数的 JSON 对象：
  • tokenCount （整数）
    请求中的标记数。

示例：

请求主体

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

响应体

  {
    "tokenCount": 23
  }