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/LocalAILocalAI 为外部 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 whats 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.jsonGET /api/instructionsGET /api/instructions/{name}SwaggerGET请求位于/swagger与/swagger/路径下这一规则的底层实现位于 core/http/auth/public_routes.gopublicRouteRegistry明确定义了 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 /versionwell-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_functionsTTS/VAD/video/3D/detection/tokenize 等、mcp、p2p、agents、settings、stores、docs。capabilities反映当前运行时配置mcp的取值为!appConfig.DisableMCPagents取值appConfig.AgentPool.Enabledp2p取值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.goinstructionDefs静态声明了每条指令的名称、描述与 tags运行时再对仓库内嵌的 Swagger spec 做按 tag 过滤动态生成指南。列出全部指令GET /api/instructionscurl 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 ?formatjson for a raw OpenAPI fragment. }可用指令全表以源码 core/http/endpoints/localai/api_instructions.go 中instructionDefs的实际定义为准当前实例可能提供取决于功能开关的指令包括InstructionDescription描述chat-inferenceChat completions、text completions、embeddingsOpenAI 兼容moderation使用本地 completion 模型进行 OpenAI 兼容文本审核audioText-to-speech、voice activity detection、transcription、speaker diarization、sound classification、sound generationvoice-library创建/预览/列出/删除可复用的语音克隆参考 profileimagesImage generation 与 inpaintingmodel-management浏览 gallery、安装、删除、管理模型与后端config-management发现、读取、修改模型配置字段并估算 VRAMmonitoring系统指标、后端状态、API 与后端 traces、后端进程日志、系统信息mcpModel Context Protocol —— 通过 MCP servers 进行 tool-augmented chatagentsAgent task 与 job 管理面向 CI/自动化video从文本 prompt 生成视频支持 image/audio conditioning3d通过 TRELLIS.2 进行 image-to-3DGLB生成face-recognition人脸 1:1 验证、1:N 识别、embedding、人口属性分析voice-recognition说话人 1:1 验证、embedding、人口属性分析branding实例白标名称、标语、logo、favicon 配置usage-and-billing按用户的 token 用量与请求计数pii-filtering查看应用于 chat 请求的 NER-based PII 过滤器middleware-admin查看与配置路由模块中间件PII filter 与 routingintelligent-routing通过每个模型上的router:配置做请求分类与模型改写注意文档正文中的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添加?formatjson可获取原始OpenAPI 片段仅含相关 path 与 definitions 的过滤版 Swagger speccurl http://localhost:8080/api/instructions/config-management?formatjson源码视角指令如何从 Swagger 生成生成管线值得展开因为它决定了指令内容为何是动态正确的首次请求时swaggerState.init()通过sync.Once将仓库内嵌的 Swagger JSONswagger.SwaggerJSON即 swagger/swagger.json解析进内存filterSwaggerByTags遍历所有 path只保留 operation 上带有该 instruction 任一 tag 的方法并通过collectRefs递归收集这些路径用到的所有$ref定义及其嵌套依赖组装成一份自洽的 OpenAPI 片段——因此?formatjson返回的片段不会出现引用了一个没带过来的 definition默认的 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?sectionparameters # 一次返回全部字段约 170 个按 section 分组 curl http://localhost:8080/api/models/config-metadata?sectionall源码 core/http/endpoints/localai/config_meta.go 中的行为不带?section时返回轻量 section 索引hintsections数组每一项带url指向对应 sectionsectionall返回全部传了不存在的 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 的AutocompleteEndpointbackends从系统状态读取已安装后端并排序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。若模型配置不存在则返回 404curl 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_size8192. The models 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表示 fp16context_size—— 估算所用的上下文窗口。在 core/http/endpoints/localai/vram.go 的VRAMEstimateEndpoint中估算委托给modeladmin.EstimateVRAM按模型权重文件在多个上下文尺寸下计算。源码还保留了一个向后兼容分支当模型没有权重文件、无法估算时返回旧的{message: no weight files found for estimation}形态而非类型化响应Agent 侧应同时兼容两种响应结构。Agent / 工具开发者的接入指南综合以上发现面一个推荐的接入工作流Discover发现请求/.well-known/localai.json得到可用端点与能力开关先判断当前实例是否启用 MCP、Agent、P2P 等功能。Browse instructions浏览指令请求/api/instructions获得指令区域总览选择与本任务相关的主题。Deep dive深入请求/api/instructions/{name}取回该主题的 markdown API 指南需要结构化原始规格则加?formatjson据此获得参数表格、请求/响应结构与注意事项。Authenticate认证在调用任何被公布的受保护端点前先按 authentication 指南 获取凭据。Explore config探查配置使用 admin 凭据访问/api/models/config-metadata及autocomplete/*来理解当前模型配置字段——这相当于用机器可读方式读完模型配置手册。Interact交互用凭据调用推理端点与配置 APIGET/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.EchoWrapHandlerSwagger 文档 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考