# Infer Runtime

一个本地优先的异构 AI 推理控制平面：应用提交 Intent 与约束，由 Runtime 在本地、云端和订阅式资源之间完成可解释的准入、路由、队列、资源与预算治理。

## Metadata

- HTML: https://glenzli.com/projects/infer-runtime/
- Markdown: https://glenzli.com/projects/infer-runtime.md
- Collection: Projects
- Language: zh-CN
- Published: 2026-08-14
- Status: active
- Tags: inference, control-plane, local-first, multimodal, consumer-contract, infra-protocol

## Content

`infer-runtime` 是一个面向个人基础设施的 AI 推理控制平面。应用不必绑定某个 Provider、模型名或部署地址，而是提交稳定的 Intent，以及质量、延迟、位置、隐私、预算和回退约束；Runtime 再依据当前资源与策略完成准入、候选选择、排队、预留、执行、取消、计量和故障切换。

它统一的是控制平面，不是所有数据平面。文本可以使用 Responses 风格的 unary 或 SSE；转写、对齐、语音合成和实验性的视觉能力保留各自的 typed contract。不同模态共享身份、Job 生命周期、配额、资源治理与审计，但不会被压进一个看似通用、实际丢失语义的 JSON 或 Tensor 接口。

## 项目概念

  ![应用的 Intent 与硬约束进入本地控制平面，经过候选过滤后选择一个文本、音频、视觉或远程执行资源](/images/projects/infer-runtime-banner.webp)

## Runtime Console

  ![infer-runtime Console 使用合成数据展示任务、Provider、资源压力与近期活动](/images/projects/infer-runtime-overview.webp)
  仓库提供的实际 Console 界面，数据均为合成示例，不代表任何本机模型、Provider 或运行状态。

## 应用表达需求，Runtime 选择落点

```text
App Intent + constraints
  -> admission and App policy
  -> Model Profile -> Build -> Deployment
  -> queue + quota + resource reservation
  -> Provider execution
  -> Job result + Attempt provenance + usage
```

`model` 字段在普通 Consumer 侧填写的是 `text.summarize`、`assistant.general`、`audio.transcribe` 这一类稳定 Intent，而不是 Ollama tag、量化文件或云端模型名。Runtime 将 Intent 解析到能力要求，再在已经准入的 Model Profile、Build、Deployment 与 Provider 中形成 Candidate Plan。

    **硬约束不会被回退放宽**
    <code>local_only</code>、offline、模态外发权限、预算、deadline 与质量下限在 fallback 时仍然成立；没有合格候选就明确失败。

    **Job 与 Attempt 分开记录**
    Job 保存应用意图与最终状态；每次实际落点形成独立 Attempt。重试和故障切换不会覆盖先前的选择、错误与用量。

    **选择过程可以解释**
    Candidate Plan、reason code、Provider 健康、预算预留与物理执行来源均被保留，不用一个不可见的综合分数代替原因。

    **本地优先不等于只跑本地模型**
    控制、配置与数据所有权留在本机；一次请求是否进入本地、云端或订阅式 Provider，由 App 授权、请求约束和实时资源共同决定。

## 一套控制面，多种真实数据面

| 协议族 | 当前形态 | 共享的控制能力 |
| --- | --- | --- |
| 文本 | Responses-shaped unary/SSE，以及可选的本地加密 background | Intent 路由、队列、取消、预算、retry/fallback 与用量结算 |
| 音频 | 文件转写、强制对齐、语音合成、声音设计与声音克隆等类型化接口 | App ACL、资源预留、Job/Attempt、限流与审计 |
| 视觉 | ONNX Session Registry，以及收窄的人脸和图文向量实验切片 | placement、敏感模态授权、原生 lifecycle 与 provenance |
| Provider | Ollama、MLX、ONNX、本地或云端 Responses，以及实验性的订阅桥 | 准入、健康、容量、熔断、资源压力和可解释候选计划 |

原生执行器仍保留自己的生命周期。Ollama、MLX 和 ONNX 不会被假装成完全相同的后端，但它们接受统一的 admission、reservation、pressure policy 与可观测边界。自动 eviction 默认关闭；可能产生真实计费或改变模型驻留状态的操作需要 Operator 明确触发。

  ![infer-runtime Console 的模型与资源页面，分别展示文本、音频、视觉和云端 Provider](/images/projects/infer-runtime-models.webp)

## Consumer 如何接入

产品应用通过 [Infra Protocol](https://github.com/glenzli/infra-protocol) 精确发现 `infer-runtime.consumer-core@20260813.1` 的 binding 与当前 endpoint，而不是长期硬编码端口。发现清单只提供候选入口与 Runtime generation；Consumer 仍须实际连接并在每个请求里声明 Core contract。官方 `infer-runtime-client` 把 discovery、generation 变化后的重新发现、owner-only token、握手和稳定错误解析收在一起，避免每个产品重复实现这层细节。

每个 Consumer 在 Console 中拥有独立 App 身份、Intent 白名单、placement、priority、quality、fallback、成本和模态外发上限；managed token 只在创建或轮换时显示一次。普通应用只获得自己的任务视图，资源控制、Provider probe 和凭证管理仍属于受保护的 Operator surface。

```bash
curl "$INFER_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $INFER_API_KEY" \
  -H 'Infer-Consumer-Contract: infer-runtime.consumer-core@20260813.1' \
  -H 'Infer-Capability-Contract: infer.responses@20260812.1' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "text.summarize",
    "input": "需要总结的内容",
    "metadata": {
      "infer.placement": "local_only",
      "infer.fallback": "none"
    }
  }'
```

请求字段严格校验；Consumer 根据 HTTP status 和稳定的 `error.code` 分支，并忽略未来可能增加的响应字段。模型和 Provider 的物理选择始终由 Runtime 记录为 Job、Attempt、Candidate Plan 和 provenance；应用表达的是意图与边界，不需要猜测当前正在使用的底层落点。

## 它刻意不做什么

`infer-runtime` 不是 Agent 框架、模型市场或 AI 应用，不接管 planning、tool loop、memory、workspace、RAG 和领域工作流。它也不替代那些契约本身就要求特定厂商能力的原生 API。

当前实现正在收口本机 Consumer 的 hard migration，而不是作为正式对外发布版。多 Provider 路由、可靠性、配额、持久化、本地资源与后台任务的核心纵向切片已经闭环；完整 traces、长期混合负载和更多连续 Consumer 使用仍属于正式 v0.1 的收口条件。ONNX/Core ML 视觉、流式音频和订阅式推理桥保持 experimental，不会因为配置存在就被当作稳定合同。