LocalAI API 发现与指令系统：面向 Agent 与自动化工具的可编程 API 发现指南

LocalAI API 发现与指令系统：面向 Agent 与自动化工具的可编程 API 发现指南

【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI

LocalAI 为外部 Agent、编码助手与自动化工具内置了一套可编程的 API 发现体系：通过/.well-known/localai.json、/api/instructions与/api/models/capabilities等只读端点，客户端无需事先阅读文档即可得知当前实例暴露了哪些能力、如何调用、以及每个模型能接收或产生何种模态的输入输出。本文将以 LocalAI 仓库的 api-discovery.md 为主线，结合 core/http/routes/localai.go 等源码中的真实路由注册与处理逻辑，完整讲解 discovery 层、指令 API、模型能力探测与配置管理 API 的用法，并给出一套可直接落地的 Agent 接入流程。

为什么需要 API 发现层

大模型应用（Agent、RAG、MCP 客户端）面对的是一个运行时能力会变化的实例：是否启用 MCP、是否运行 Agent 池、是否开启 P2P、装了什么后端、哪个模型支持视觉或多模态输入，全部由启动时的运行配置与已安装模型决定。传统做法是让调用方预先阅读 README，然后硬编码 URL——一旦实例配置变化就会出现 404 或语义错误。

LocalAI 的设计思路是把"实例当前能做什么"本身变成可查询的元数据。在 core/http/routes/localai.go 中可以清楚看到这一层被注册在普通的模型路由之外，且刻意不挂鉴权中间件（见下文"认证与发现"）。三个最核心的发现面分别是：

• /.well-known/localai.json—— 实例级能力清单（版本 + 全部端点 + 运行能力开关）；
• /api/instructions与/api/instructions/{name}—— 按主题组织、面向 LLM 的可读 API 指南；
• /v1/models/capabilities—— 模型级能力清单（多模态输入输出）。

下面先给出三分钟上手的 Quick Start。

Quick start

假设 LocalAI 默认监听localhost:8080：

# 1. Discover what's available curl http://localhost:8080/.well-known/localai.json # 2. Browse instruction areas curl http://localhost:8080/api/instructions # 3. Get an API guide for a specific instruction curl http://localhost:8080/api/instructions/config-management

第 1 步拿到实例级能力总览，第 2 步看到所有指令主题的清单，第 3 步针对"配置管理"主题取回一份完整、可执行的 API 指南。这三条命令都不需要任何凭据。

认证与发现：读免费、用受限

LocalAI 对"发现面"与"受保护面"做了明确区分。在开启数据库认证或传统 API Key 时，以下 surface仍然可以匿名读取：

• GET /.well-known/localai.json
• GET /api/instructions
• GET /api/instructions/{name}
• SwaggerGET请求，位于/swagger与/swagger/路径下

这一规则的底层实现位于 core/http/auth/public_routes.go：publicRouteRegistry明确定义了 Discovery 分组的四条匹配规则（GET /api/instructions、前缀/api/instructions/、GET /swagger、前缀/swagger/、GET /.well-known/localai.json），鉴权中间件通过isPublicRoute在命中时直接放行。同文件还可见GET /healthz、/readyz以及/api/auth/*引导路由等同样公开。

需要特别强调边界：发现不等于授权。discovery 只是把端点 URL 告诉了你，被它公布出来的端点本身通常仍需要凭据，除非 authentication 指南 将之列为 public discovery 或 bootstrap 路由。典型例子是GET /version：well-known 响应里包含实例版本号，但你仍然需要携带凭据才能直接调用/version（路由注册在 core/http/routes/localai.go，该端点带 admin 中间件之外的版本返回逻辑）。此外，配置管理相关端点（见下文）要求admin 认证；而 UI 编排文件 core/http/routes/ui_api.go 中同一批配置端点在注册时全部显式挂了adminMiddleware。

Well-Known Discovery Endpoint：实例级能力总览

GET /.well-known/localai.json返回三个信息块：实例版本、全部可用端点 URL（扁平列表 + 分类分组）、以及运行时能力开关。

示例响应（已缩写，字段以真实响应为准）：

{ "version": "v2.28.0", "endpoints": { "chat_completions": "/v1/chat/completions", "models": "/v1/models", "models_capabilities": "/v1/models/capabilities", "config_metadata": "/api/models/config-metadata", "instructions": "/api/instructions", "swagger": "/swagger/index.html" }, "endpoint_groups": { "openai_compatible": { "chat_completions": "/v1/chat/completions", "..." : "..." }, "config_management": { "config_metadata": "/api/models/config-metadata", "..." : "..." }, "model_management": { "..." : "..." }, "monitoring": { "..." : "..." } }, "capabilities": { "config_metadata": true, "config_patch": true, "vram_estimate": true, "mcp": true, "agents": false, "p2p": false } }

源码视角：这些字段从哪来

well-known 端点的完整实现直接内联在 core/http/routes/localai.go 的路由闭包中，可以观察到几个值得注意的设计：

• 扁平endpoints用于向后兼容：代码注释明确写道 "Flat endpoint list for backwards compatibility"，其中config_patch与config_json指向同一 URLconfig-json/:name（一个 GET 一个 PATCH），并额外公布了model_load_status、tts、voice_profiles、transcription、image_generation等快捷入口。
• endpoint_groups是结构化分类视图，真实分组远比示例丰富：除openai_compatible、config_management、model_management、monitoring外，还包括ai_functions（TTS/VAD/video/3D/detection/tokenize 等）、mcp、p2p、agents、settings、stores、docs。
• capabilities反映当前运行时配置：mcp的取值为!appConfig.DisableMCP，agents取值appConfig.AgentPool.Enabled，p2p取值P2PToken != ""——这正是文档所述"capabilities 反映运行时配置"的直接代码证据。除此之外还固定上报config_metadata、config_patch、vram_estimate、tracing、voice_profiles为true。
• monitoring分组随部署形态变化：当appConfig.Distributed.Enabled为假（单机）时发布/api/backend-logs系列与/ws/backend-logs/:modelIdWebSocket 日志流；分布式模式下则替换为/api/nodes/:id/backend-logs等节点代理路由。

作为 Agent，你应该把该响应当作"引导页面"：先读它来决定接下来要调用的端点和该拿什么样的凭据。

Instructions API：面向 LLM 的按主题 API 指南

Instructions（指令）是一组经过人工策展、彼此相关的 API 端点的集合。每一条 instruction 映射到一个或多个 Swagger tag，并对外提供一份聚焦的、LLM 可直接阅读的指南。其数据与逻辑位于 core/http/endpoints/localai/api_instructions.go：instructionDefs静态声明了每条指令的名称、描述与 tags；运行时再对仓库内嵌的 Swagger spec 做按 tag 过滤，动态生成指南。

列出全部指令

GET /api/instructions

curl http://localhost:8080/api/instructions

返回一份紧凑的指令清单，例如：

{ "instructions": [ { "name": "chat-inference", "description": "OpenAI-compatible chat completions, text completions, and embeddings", "tags": ["inference", "embeddings"], "url": "/api/instructions/chat-inference" }, { "name": "config-management", "description": "Discover, read, and modify model configuration fields with VRAM estimation", "tags": ["config"], "url": "/api/instructions/config-management" } ], "hint": "Fetch GET {url} for a markdown API guide. Add ?format=json for a raw OpenAPI fragment." }

可用指令全表

以源码 core/http/endpoints/localai/api_instructions.go 中instructionDefs的实际定义为准，当前实例可能提供（取决于功能开关）的指令包括：

注意：文档正文中的"Available instructions"表只列了 9 项，而仓库实际注册的指令更多（如moderation、3d、face-recognition、voice-recognition、intelligent-routing等）。写入接入逻辑时应以GET /api/instructions的运行时返回为准——它天然只包含当前构建支持的指令。

获取单条指令指南

GET /api/instructions/:name

默认返回适合 LLM 与人类阅读的Markdown 指南：

curl http://localhost:8080/api/instructions/config-management

添加?format=json可获取原始OpenAPI 片段（仅含相关 path 与 definitions 的过滤版 Swagger spec）：

curl http://localhost:8080/api/instructions/config-management?format=json

源码视角：指令如何从 Swagger 生成

生成管线值得展开，因为它决定了指令内容为何是"动态正确"的：

1. 首次请求时，swaggerState.init()通过sync.Once将仓库内嵌的 Swagger JSON（swagger.SwaggerJSON，即 swagger/swagger.json）解析进内存；
2. filterSwaggerByTags遍历所有 path，只保留 operation 上带有该 instruction 任一 tag 的方法，并通过collectRefs递归收集这些路径用到的所有$ref定义及其嵌套依赖，组装成一份自洽的 OpenAPI 片段——因此?format=json返回的片段不会出现"引用了一个没带过来的 definition"；
3. 默认的 markdown 模式则由swaggerToMarkdown将片段渲染为结构化文档：为每个 path 输出## HTTP_METHOD path，把非 body 参数渲染为Name/In/Type/Required/Description表格，把 body 请求体与各响应码对应的 definition 渲染为字段表格，并用指令内置的Intro短文本补充 Swagger 之外的上下文（例如chat-inference会提示"stream": true走 SSE、tool/function calling 依赖模型配置了 function templates）。

这也是为什么指令指南能做到"不落后于代码"：只要 Swagger 注释随 handler 更新，生成的指南同步更新。测试用例 core/http/endpoints/localai/api_instructions_test.go 覆盖了列表、单条 markdown 与 JSON 三种形态的回归。

Model Capabilities：模型级能力与多模态探测

GET /v1/models/capabilities

这是/v1/models的LocalAI 私有、纯增量（additive）扩展：返回同样的模型集合，但为每个条目额外附加该模型支持的capabilities以及它接受/产出的input/output modalities。用途是让调用方在真正发起请求之前就能判断：给定模型能否直接接收一张图、一段音频或一个视频附件？还是输入必须先做转换或转写？

因为它是纯增量的，只理解/v1/models的老客户端完全不受影响——它们永远不会调用这个路由。

curl http://localhost:8080/v1/models/capabilities

{ "object": "list", "data": [ { "id": "qwen2.5-omni", "object": "model", "capabilities": ["chat", "vision", "tools"], "input_modalities": ["text", "image", "audio"], "output_modalities": ["text"] }, { "id": "parakeet", "object": "model", "capabilities": ["transcript"], "input_modalities": ["audio"], "output_modalities": ["text"] } ] }

字段语义：

• capabilities—— 规范化的 usecase 字符串（如chat、vision、transcript、tts、embeddings、image、video），可附带修饰符tools（支持函数调用）与thinking（支持推理模式）。
• input_modalities/output_modalities—— 模型接受与产生的模态，取值是{text, image, audio, video}的子集。LocalAI 综合三方面信息来源：按 usecase 的推断、后端设置（如 vLLM 的limit_mm_per_prompt）、以及模型级显式字段known_input_modalities/known_output_modalities。显式字段弥补了 usecase 无法表达的区别——例如一个视频模型同时也接受语音输入，仅凭 usecase 推断是无法得到的。

源码视角与兼容行为

实现在 core/http/endpoints/openai/list_capabilities.go 中：ListModelCapabilitiesEndpoint先调用与/v1/models相同的listVisibleModelNames（共享可见模型集合解析逻辑），再对每个模型从ModelConfig读取cfg.Capabilities()、cfg.InputModalities()、cfg.OutputModalities()拼装响应。

文档特别说明它与/v1/models兼容的细节，在实现里同样成立：

• /v1/models支持的查询参数在这里同样生效（filter、excludeConfigured）；
• 开启认证时，同样的 per-user 模型 allowlist 也会应用（listVisibleModelNames接收可选的authDB用于用户可见性过滤）。

Configuration Management APIs：让 Agent 具备配置模型的能力

这一组端点允许 Agent 发现模型配置字段、读取当前设置、修改它们并估算 VRAM 占用。所有端点位于 core/http/routes/ui_api.go 的/api/models/*注册块，全部受adminMiddleware保护。

警告：配置管理端点要求admin 认证（在配置了认证的情况下）。well-known 端点、instructions API 与 SwaggerGET路由保持匿名可用。

Config metadata：发现全部配置字段

GET /api/models/config-metadata

返回所有模型配置字段的结构化元数据，按 section 组织。每个字段包含 YAML 路径、Go 类型、UI 类型、label、描述、默认值、校验约束与可选值。该元数据由 core/config/meta 基于config.ModelConfig的 Go struct 反射生成（见ConfigMetadataEndpoint中meta.BuildConfigMetadata(reflect.TypeOf(config.ModelConfig{}))）。

# 仅返回 section 索引（轻量，默认行为） curl http://localhost:8080/api/models/config-metadata # 返回某个 section 的字段 curl http://localhost:8080/api/models/config-metadata?section=parameters # 一次返回全部字段（约 170 个，按 section 分组） curl http://localhost:8080/api/models/config-metadata?section=all

源码 core/http/endpoints/localai/config_meta.go 中的行为：不带?section时返回轻量 section 索引（hint+sections数组，每一项带url指向对应 section）；section=all返回全部；传了不存在的 section 返回 404。指令config-management的Intro提示了元数据的使用约定：静态可选项的字段在元数据里带options数组；动态取值的字段带autocomplete_provider，需要运行时查询（见下节）。

Autocomplete values：动态字段的运行时取值

GET /api/models/config-metadata/autocomplete/:provider

对动态字段返回运行时可用的值。provider 包括backends、models、models:chat、models:tts、models:transcript、models:vad。

# 列出已安装后端 curl http://localhost:8080/api/models/config-metadata/autocomplete/backends # 列出支持 chat 的模型 curl http://localhost:8080/api/models/config-metadata/autocomplete/models:chat

实现位于 core/http/endpoints/localai/config_meta.go 的AutocompleteEndpoint：backends从系统状态读取已安装后端并排序；models合并了有配置文件与无配置（loose/autodetect）两类模型；models:<capability>使用BuildUsecaseFilterFn按 usecase 过滤（chat/tts/vad/transcript/score/token-classify 均可，score 即 router 分类器 usecase）。响应形如{"values": ["..."]}。

读取模型配置

GET /api/models/config-json/:name

返回指定模型的完整配置（JSON）。若模型配置不存在则返回 404：

curl http://localhost:8080/api/models/config-json/my-model

更新模型配置

PATCH /api/models/config-json/:name

将 JSON patch深度合并进现有模型配置——只写你想改的字段即可，未提及的字段原样保留。端点会校验合并后的配置并以 YAML 形式落盘：

curl -X PATCH http://localhost:8080/api/models/config-json/my-model \ -H "Content-Type: application/json" \ -d '{"context_size": 16384, "gpu_layers": 40}'

实现位于 core/http/endpoints/localai/config_meta.go 的PatchConfigEndpoint，其要点：

• 模型名会先做url.PathUnescape解码；
• patch 通过modeladmin.NewConfigService(...).PatchConfig完成深度合并、校验并写回 YAML 磁盘文件；
• 成功响应包含success、message、config_revision（配置修订号）与pending_cleanup字段；
• 在分布式模式下，patch 后还会调用gs.BroadcastModelsChangedRevision(modelName, "install", ...)向对端广播修订，保证多副本配置一致（单机模式为 no-op）。

VRAM estimation：发送前先评估显存

POST /api/models/vram-estimate

基于模型的权重文件、上下文大小与 GPU 层卸载数量估算一个已安装模型的 VRAM 占用：

curl -X POST http://localhost:8080/api/models/vram-estimate \ -H "Content-Type: application/json" \ -d '{"model": "my-model", "context_size": 8192}'

{ "sizeBytes": 4368438272, "sizeDisplay": "4.4 GB", "vramBytes": 6123456789, "vramDisplay": "6.1 GB", "context_note": "Estimate used default context_size=8192. The model's trained maximum context is 131072; VRAM usage will be higher at larger context sizes.", "model_max_context": 131072 }

可选参数：

• gpu_layers—— 需要卸载（offload）到 GPU 的层数，0表示全部卸载；
• kv_quant_bits—— KV cache 量化位数，0表示 fp16；
• context_size—— 估算所用的上下文窗口。

在 core/http/endpoints/localai/vram.go 的VRAMEstimateEndpoint中，估算委托给modeladmin.EstimateVRAM（按模型权重文件在多个上下文尺寸下计算）。源码还保留了一个向后兼容分支：当模型没有权重文件、无法估算时返回旧的{"message": "no weight files found for estimation"}形态而非类型化响应，Agent 侧应同时兼容两种响应结构。

Agent / 工具开发者的接入指南

综合以上发现面，一个推荐的接入工作流：

1. Discover（发现）：请求/.well-known/localai.json，得到可用端点与能力开关，先判断当前实例是否启用 MCP、Agent、P2P 等功能。
2. Browse instructions（浏览指令）：请求/api/instructions，获得指令区域总览，选择与本任务相关的主题。
3. Deep dive（深入）：请求/api/instructions/{name}，取回该主题的 markdown API 指南（需要结构化原始规格则加?format=json），据此获得参数表格、请求/响应结构与注意事项。
4. Authenticate（认证）：在调用任何被公布的受保护端点前，先按 authentication 指南 获取凭据。
5. Explore config（探查配置）：使用 admin 凭据访问/api/models/config-metadata（及autocomplete/*）来理解当前模型配置字段——这相当于用机器可读方式"读完"模型配置手册。
6. Interact（交互）：用凭据调用推理端点与配置 API（GET/PATCH /api/models/config-json/:name、POST /api/models/vram-estimate）；在多模态场景可先用/v1/models/capabilities判断附件是否需要预转换。

一个端到端的时序示例：Agent 收到"帮我把 my-model 的上下文调到 16K 并在 40 层 GPU 卸载下估算显存"这类任务时，可以完全不依赖人工文档——先 GET well-known 确认config_metadata/config_patch/vram_estimate能力为true，再取config-management指令拿到字段表，然后依次 PATCHcontext_size: 16384、gpu_layers: 40，最后 POST vram-estimate 拿到可决策的显存数字。

Swagger UI：人工交互式文档

完整的交互式 API 文档可在无需认证的情况下访问/swagger/index.html。该入口同时被 well-known 响应的docs分组与扁平endpoints列表收录（"swagger": "/swagger/index.html"）。

需要重申的是：从 Swagger UI 向受保护端点发出的请求仍然需要凭据——Swagger 只是文档浏览入口，不改变端点自身的鉴权边界。路由注册见 core/http/routes/localai.go 中的echoswagger.EchoWrapHandler（Swagger 文档 URL 被配置为doc.json），对应的 OpenAPI 定义由 swagger/swagger.json 与 swagger/docs.go 承载，它们也正是 instructions API 生成 markdown/OpenAPI 片段时的数据源。

小结

LocalAI 的 discovery 体系把"这个实例现在能做什么、怎么做"沉淀为四个可匿名读取的只读入口（well-known、instructions、Swagger），叠加一个带鉴权的"运行时模型能力/配置操作面"（model capabilities 与 config management 系列），使 Agent、编码助手与自动化流水线能够：零预读文档地完成端点发现 → 主题化学习 → 模型模态判断 → 配置读写 → 显存评估 → 推理调用的完整闭环。对构建通用型 AI 工具链的开发者而言，这套机制的价值在于：客户端对实例"先探测、后使用"，配置的漂移与模型的增删都不再需要人工同步文档或硬编码 URL。

【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI