Foundry Local REST API 参考

OpenAI v1 兼容性

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

自定义 API

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。

POST /openai/register

注册外部模型提供程序以供 Foundry Local 使用。

请求正文：

• TypeName（字符串）
  提供程序名称（例如 "deepseek"）
• ModelName（字符串）
  要注册的模型名称（例如 "deepseek-chat"）
• BaseUri（字符串）
  提供程序的 OpenAI 兼容基 URI

响应：

• 200 正常
  空响应正文

示例：

• 请求正文

  {
    "TypeName": "deepseek",
    "ModelName": "deepseek-chat",
    "BaseUri": "https://api.deepseek.com/v1"
  }
  

GET /openai/models

获取所有可用的模型，包括本地模型和已注册的外部模型。

响应：

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

示例：

• 响应正文

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

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}

Unload a model from memory.

**URI Parameters:**

- `name` (string)  
  The model name to unload.

**Query Parameters:**

- `force` (boolean, optional)  
  If `true`, ignores TTL settings and unloads immediately.

**Response:**

- 200 OK  
  Empty response body

**Example:**

- Request URI
  ```http
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 /openai/download

Download a model to local storage.

> [!NOTE]
> Large model downloads can take a long time. Set a high timeout for this request to avoid early termination.

**Request Body:**

- `model` (`WorkspaceInferenceModel` object)
  - `Uri` (string)  
    The model URI to download.
  - `Name` (string)
    The model name.
  - `ProviderType` (string, optional)  
    The provider type (for example, `"AzureFoundryLocal"`, `"HuggingFace"`).
  - `Path` (string, optional)  
    Remote path to the model files. For example, in a Hugging Face repository, this is the path to the model files.
  - `PromptTemplate` (`Dictionary<string, string>`, optional)  
    Includes:
    - `system` (string, optional)  
      The template for the system message.
    - `user` (string, optional)
      The template for the user's message.
    - `assistant` (string, optional)  
      The template for the assistant's response.
    - `prompt` (string, optional)  
      The template for the user-assistant interaction.
  - `Publisher` (string, optional)  
     The publisher of the model.
- `token` (string, optional)  
  Authentication token for protected models (GitHub or Hugging Face).
- `progressToken` (object, optional)  
  For AITK only. Token to track download progress.
- `customDirPath` (string, optional)  
  Custom download directory (used for CLI, not needed for AITK).
- `bufferSize` (integer, optional)  
  HTTP download buffer size in KB. No effect on NIM or Azure Foundry models.
- `ignorePipeReport` (boolean, optional)  
  If `true`, forces progress reporting via HTTP stream instead of pipe.
  Defaults to `false` for AITK and `true` for Foundry Local.

**Streaming Response:**

During download, the server streams progress updates in the format:

```text
("file name", percentage_complete)

最终响应正文：

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

示例：

• 请求主体

{
  "model": {
    "Uri": "azureml://registries/azureml/models/Phi-4-mini-instruct-generic-cpu/versions/4",
    "ProviderType": "AzureFoundryLocal",
    "Name": "Phi-4-mini-instruct-generic-cpu",
    "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)

- Final response
  ```json
  {
    "Success": true,
    "ErrorMessage": null
  }

GET /openai/status

获取服务器状态信息。

响应正文：

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

示例：

• 响应正文

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

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
  }