LocalAI Assistant用自然语言聊天管理 LocalAI 的管理型 MCP 助手实战指南【免费下载链接】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 Assistant 是 LocalAI 内置的“管理员专用聊天模式”当一个聊天会话开启该模式后对话会被接入一个运行在进程内的 MCPModel Context Protocol服务器该服务器把 LocalAI 自身的安装模型、管理后端、编辑模型配置、查看系统状态等管理操作全部封装成 MCP 工具管理员只需“说话”即可完成管理全程无需 REST 调用、无需手写 YAML。本文以 docs/content/features/localai-assistant.md 为骨架结合pkg/mcp/localaitools/、core/http/endpoints/mcp/、core/cli/等源码实现从启用方式、安全模型、工具清单、独立 stdio 部署到二次开发完整讲解读完后你既能上手使用也能理解其底层机制并自行扩展。一、功能定位一种“可对话的管理员入口”LocalAI Assistant 本质上是 LocalAI 管理面admin/management surface的MCP 化封装。它区别于普通聊天的是三个特征仅面向管理员admin-only非管理员在界面上看不到开启入口聊天处理器也会在请求时刻二次校验管理员角色。不经过 HTTP 回环MCP 服务器直接跑在 LocalAI 进程内通过配对的net.Pipe()内存传输与聊天会话相连没有 localhost 回环端口、没有伪造的管理 API Key、没有额外的 TCP socket。两种运行形态共享同一套代码进程内in-process管理员在聊天 UI 中以metadata.localai_assistanttrue开启后聊天处理器把内存 MCP 服务器注入会话LLM 通过“聊天”即可安装模型、管理后端、编辑模型配置。独立 stdiostandalone通过local-ai mcp-server子命令把同一套管理工具以 stdio MCP 服务器形式对外提供可指向任意远程 LocalAI HTTP API如从桌面 MCP 客户端、Cursor、mcphost中远程操作 LocalAI。官方包文档在 pkg/mcp/localaitools/doc.go 中明确说明了这两种用法并指出“工具处理器与内嵌的技能提示skill prompts只面向LocalAIClient接口与底层传输/实现完全无关”。core/http/endpoints/mcp/localai_assistant.go中更进一步解释了为什么用一个进程级 holder 而非每次请求都建一对传输MCP 服务器在请求之间是无状态的复用同一对net.Pipe()与同一个LocalToolExecutor可以省掉反复建连与重复枚举工具的消耗。二、核心架构一次封装、两处复用2.1 包结构与目录职责管理 MCP 服务器整体位于公共 Go 包pkg/mcp/localaitools/.agents/localai-assistant-mcp.md中的“File map”给出了权威目录映射文件/目录职责client.goLocalAIClient接口定义与 DTO 注册表dto.go两个 client 实现共用的 JSON 标签 DTO不允许暴露裸 service 类型server.goNewServer(client, opts)—— 构建并注册全部工具的 MCP 服务器tools.goTool*工具名常量单一事实来源禁止散落裸字符串tools_*.go按功能分组的工具注册models/backends/config/system/state/scheduling/branding/voice_profiles/usage/pii/middleware/aliasesprompts.go//go:embed加载器 SystemPrompt(opts)系统提示组装prompts/*.md角色00_role.md、安全规则10_safety.md、工具目录20_tools.mdprompts/skills/*.md技能配方教 LLM“怎么干活”的 markdown按字典序自动拼入系统提示inproc/client.go进程内LocalAIClient直接调用 service不走 HTTP 回环httpapi/client.go走 REST 的LocalAIClient供独立 CLI / 远程实例使用2.2 服务器构建与可选参数pkg/mcp/localaitools/server.go 中Options提供三个开关DisableMutating bool为true时跳过所有会改动服务端状态的工具注册独立 CLI 的--read-only模式即依赖它。ServerName string覆盖 MCP 服务器对外通告的Implementation.Name默认localai-admin。ServerVersion string覆盖通告版本默认取internal.PrintableVersion()。NewServer依据传入的LocalAIClient依次调用registerModelTools、registerBackendTools、registerConfigTools、registerSystemTools、registerSchedulingTools、registerStateTools、registerBrandingTools、registerVoiceProfileTools、registerUsageTools、registerPIITools、registerMiddlewareTools、registerAliasTools等完成注册并把SystemPrompt(opts)作为mcp.ServerOptions.Instructions注入。2.3 系统提示的自动拼装机制pkg/mcp/localaitools/prompts.go 通过//go:embed prompts/*.md prompts/skills/*.md把全部 markdown 打进二进制随后SystemPrompt按字典序遍历并拼成一段带!-- file: ... --与# section: ...头注的完整系统提示。这意味着新增prompts/skills/xxx.md无需任何 Go 改动即会自动生效每一节都标注来源文件名方便追溯“LLM 正在引用哪个技能”。2.4 为什么用两个 client 而不是“自连一次”.agents/localai-assistant-mcp.md的 “Why two clients” 一节给出了直白理由进程内模式若走 HTTP 回环LocalAI 需要为“向自己认证”铸造一个合成管理 API Key并且每次工具派发都要双重序列化还会丢失进程内通道例如GalleryService.ModelGalleryChannel用于流式上报安装进度。因此进程内用inproc.Client直接调 service独立 CLI 面对远程实例只能用httpapi.Client走 REST。二者实现同一LocalAIClient接口测试层通过 parity_test.go 保持输出等价。三、在聊天中启用 Assistant实战步骤按官方文档启用流程如下以admin用户身份打开聊天 UI并在模型选择器中选择一个支持聊天的模型。头部出现Manage开关——把它打开聊天标题旁即显示Manage mode徽标。界面上会出现一批“起手提问”快捷 chips例如“What is installed?”“Install a chat model”“Show system status”“Update a backend”首页还会暴露一个Manage by chatCTA点击后直接打开一个已处于 Manage 模式的全新聊天会话。开启后即可尝试自然语言指令例如Install Qwen 3 chat助理会按技能流程执行先在模型库gallery中搜索、列出候选、请你在编号列表中挑选、摘要将要执行的安装动作并等待你的确认然后才调用install_model安装期间它会轮询进度并向你汇报最终结果。从实现角度聊天请求通过metadata.localai_assistanttrue这个元数据声明“本会话走助理通道”该标记由core/http/endpoints/openai/chat_assistant_gate.go的requireAssistantAccess校验见下文安全模型进程内的 MCP 服务器会话则由 core/http/endpoints/mcp/localai_assistant.go 中的LocalAIAssistantHolder持有工具列表在应用启动时预发现首个聊天请求不必再付一次list_tools往返开销。四、关闭特性关闭 LocalAI Assistant 有两种方式粒度不同运行期关闭在Settings → LocalAI Assistant中关掉开关立即生效、无需重启。启动期硬关闭设置环境变量后启动LOCALAI_DISABLE_ASSISTANTtrue local-ai run关闭后的行为聊天处理器会拒绝携带metadata.localai_assistanttrue的请求并返回503界面上的 Manage 开关被隐藏。这与源码中的处理一致LocalAIAssistantHolder在DisableLocalAIAssistant为真或初始化失败时Executor()返回空的LocalToolExecutor、HasTools()为false聊天处理器据此判定“功能不可用”。五、安全模型层层防护官方文档与源码共同确认了这套安全模型界面层Manage 开关对非管理员用户隐藏聊天 UI 由前端按角色渲染。请求层纵深防御即便认证配置被设为“跳过助理功能门禁”聊天处理器仍会在请求时刻重新校验管理员角色。core/http/endpoints/openai/chat_assistant_gate.go 的实现如下当认证开启时取出当前用户若用户不存在或user.Role ! auth.RoleAdmin直接返回403 localai_assistant requires admin只有认证整体被关闭时该校验才是 no-op此时操作者选择信任所有调用方。网络层MCP 服务器跑在进程内使用net.Pipe()配对传输不存在 localhost 回环、合成 API Key 或额外 TCP socket天然没有可被外部探测的管理端口。行为层提示词强制确认所有变更型工具install_model、delete_model、edit_model_config、upgrade_backend等都由系统提示中的安全规则约束要求 LLM 在调用前先向用户明确说明动作并获得确认代码层没有额外的 preview/apply 两阶段。.agents/localai-assistant-mcp.md明确说这是 KISS 设计选择新增变更型工具时不要加 Go 代码层面的确认逻辑只需把工具名登记进prompts/10_safety.md规则 1 即可。系统提示中完整的安全规则见 pkg/mcp/localaitools/prompts/10_safety.md共 5 条核心纪律变更前确认列出所有受约束工具调用前须用平实语言说明“做什么哪个工具、哪个目标、哪些参数”并等待用户下一轮的显式确认“Yes”“do it”“go ahead”“proceed”均算确认其余不算。变更前消歧请求含糊多个 gallery 候选、同一模型多个已装版本、后端存在变体时把候选列成编号清单请用户先选择。原样呈现工具错误工具返回错误时把错误原文放进 fenced code block 引用给用户不重试、不改写等待用户指示。绝不编造标识符只使用本对话中工具返回过的模型名、gallery 名、后端名与 job ID没有就先调用gallery_search/list_*工具。轮询上限轮询get_job_status时在processed: true、cancelled: true或已轮询 30 次三者中先到者停止并始终向用户总结最终结果。规则 1 的工具名单在 Go 侧由 tools.go 的mutatingToolNames常量维护prompts_test.go会自动校验名单与提示词保持一致避免“改工具忘记改安全提示”的漂移。六、独立 stdio MCP 服务器外部远程管理同一套管理工具面可以以 stdio MCP 服务器形式指向任意 LocalAI HTTP API# 完整模式连接远程实例并携带管理员 key local-ai mcp-server --target http://remote.localai:8080 --api-key admin-key # 只读模式跳过所有变更型工具的注册安装/删除/编辑/升级等均不出现 local-ai mcp-server --target http://remote.localai:8080 --read-only这样就能把 LocalAI 管理能力接入 Claude Desktop、Cursor 或任何 MCP host。其工具目录与进程内变体完全一致——两者共用localaitools.NewServer与同一套 skill prompts只是LocalAIClient实现不同。CLI 结构core/cli/mcp_server.go提供了三个可控参数并支持以环境变量覆盖参数环境变量默认值说明--targetLOCALAI_MCP_TARGEThttp://localhost:8080目标 LocalAI 基础 URL为空时报错退出--api-keyLOCALAI_API_KEY空访问目标 LocalAI 的 Bearer API Key--read-only——false为真时通过Options.DisableMutating跳过全部变更型工具注册进程内部注意点stdio 模式下 stdout 专供 JSON-RPC其它日志只能走 stderr同时使用signal.NotifyContext监听 SIGINT/SIGTERM以便宿主 Ctrl-C 或kill -TERM时给srv.Run机会排空进行中的调用。七、工具目录全览7.1 官方文档的完整清单必须原样掌握只读工具gallery_search、list_installed_models、list_galleries、list_backends、list_known_backends、get_job_status、get_model_config、vram_estimate、system_info、list_nodes。变更型工具依据助手安全提示须经用户确认install_model、import_model_uri、delete_model、install_backend、upgrade_backend、edit_model_config、reload_models、toggle_model_state、toggle_model_pinned。7.2 源码注册的完整目录比文档更全的现行事实从 tools.go 的常量与 prompts/20_tools.md 的“策展式”描述看实际注册的工具面比 feature 文档列举的更广二者并不冲突——feature 文档是入门入口tools.go是运行时真相。整理为下表类别工具一句话说明只读gallery_search在已配置的模型库中搜索可安装模型只读list_installed_models列出已装模型支持capability过滤chat/embed/image等只读list_galleries/list_backends/list_known_backends列出已配置 gallery / 已装后端 / 可从后端库安装的后端只读get_job_status按 job id 轮询安装/删除/升级任务状态只读get_model_config读取已装模型的 YAML/JSON 配置只读vram_estimate/system_info/list_nodes显存估算 / LocalAI 版本与路径等系统信息 / 分布式联邦节点列表只读list_scheduling/get_scheduling分布式按模型调度配置的列表与单条读取只读list_voice_profiles/get_branding语音克隆档案列表 / 实例名与标语读取只读get_usage_stats/get_pii_events/get_middleware_status用量聚合 / PII 过滤事件 / 中间件状态只读探查只读get_router_decisions/get_router_corpus_stats/list_aliasesKNN 路由决策与语料统计只返回计数与标签绝不返回示例文本/ 别名清单变更install_model/import_model_uri从 gallery 安装模型返回 job id用get_job_status轮询/ 从任意 URIHuggingFace、OCI、http(s)、file://导入多后端适用时返回ambiguous_backend需以backend_preference再次调用变更delete_model/edit_model_config/reload_models删除模型 / 深合并 JSON 补丁到已装模型配置 / 从磁盘重载全部模型配置变更load_model预载模型进内存消除首请求冷启动对实时管线模型会加载全部子模型VAD、转写、LLM、TTS 等变更install_backend/upgrade_backend安装后端 / 按名升级已装后端变更toggle_model_state/toggle_model_pinned启停模型action:enable/disable/ 固定与取消固定action:pin/unpin变更set_branding/set_alias修改实例名或标语 / 增改删模型别名变更seed_router_corpus/clear_router_corpus向 KNN 路由语料加入带标签样本 / 永久清空语料与活动索引变更create_voice_profile/delete_voice_profile保存经同意的 base64 PCM-WAV 参考音与精确转写供 TTS 复用 / 按 UUID 永久删除档案变更set_node_vram_budget/set_scheduling/delete_scheduling设置/清除联邦节点 VRAM 预算覆盖 / 增改/删除分布式按模型调度配置注意一个容易踩的细节.agents/localai-assistant-mcp.md的代码约定list_installed_models的 capability 过滤用的是capability.go中类型化的Capability常量只接受规范值如CapabilityEmbeddings不存在embed/embedding互为别名这类宽松匹配。八、技能配方SkillsLLM 的操作手册除角色与安全规则外prompts/skills/下现有 8 个按“动词_名词.md”命名的技能文件configure_branding.md # 配置品牌实例名/标语 edit_model_config.md # 修改模型配置 import_model_from_uri.md # 从 URI 导入模型 install_chat_model.md # 安装聊天模型含冷启动引导 manage_distributed_scheduling.md manage_router_corpus.md system_status.md # 汇报系统状态 upgrade_backend.md # 升级后端以 install_chat_model.md 为例可见技能配方如何“把一次完整安装拆成可验证的步骤序列”用用户的查询调用gallery_search用户明确要聊天模型时加tag: chat以编号列表展示前几名结果含名称、gallery、简介与许可无匹配就说明并询问是否放宽搜索等待用户挑选摘要将要安装的gallery/name如“我将安装gallery/name确认吗”并等待确认确认后以gallery_name与model_name调用install_modelvariant留空让 LocalAI 依据本机引擎与空闲内存自动挑选能跑的最大构建仅当用户点名具体构建如“Q8 那个”时才精确填写列表中的名字——写错名字会导致安装失败而不是回退到自动选择用返回的 job id 轮询get_job_status报告有意义的进度变化每约 10%–20%外加完成processed: true且无错误后调用reload_models再用capability: chat的list_installed_models确认模型已可见告知用户模型已就绪以及聊天补全接口中应填写的model名称。该文件还要求install_model失败时原样呈现错误并询问“重试 / 换模型 / 放弃”。这些配方通过//go:embed自动拼入系统提示字典序、带来源头注LLM 在收到用户请求时据此决定调用哪些工具、问什么问题、如何收尾。九、为 Assistant 新增工具或技能扩展指南.agents/localai-assistant-mcp.md给出了完整的三层同步契约与新增检查清单面向所有“会碰 LocalAI 管理面”的人人类或 AI Agent“三层必须同步”当你改动 LocalAI 管理面时以下三层必须保持一致否则聊天管理端看不到新功能——REST 端点core/http/endpoints/localai/*.go并在core/http/routes/localai.go中以auth.RequireAdmin()门禁MCP 工具注册在pkg/mcp/localaitools/tools_*.go注册工具 在client.go的LocalAIClient接口加方法 在inproc/client.go与httpapi/client.go各加实现技能提示在prompts/skills/下新增/更新 markdown教 LLM 何时调用该工具、先问用户什么、出错怎么办。新增管理端点的检查清单要点REST 端点存在且以auth.RequireAdmin()门禁LocalAIClient接口含覆盖新操作的 methodDTO 加进dto.goJSON 打标签绝不暴露裸 service 类型inproc/client.go直接调 service不走 HTTP 回环httpapi/client.go调对应 REST 端点在合适的tools_*.go注册工具变更型工具须在描述中引用安全规则 1变更型工具须保证Options{DisableMutating: true}会跳过它参考tools_models.go的模式更新/新增prompts/skills/下的技能文件测试补齐把工具名加进 server_test.go 的expectedFullCatalog只读则加进expectedReadOnlyCatalog把派发用例加进TestEachToolDispatchesToClient并在httpapi/client_test.go覆盖新 HTTP 路径。新增技能配方无需新工具在prompts/skills/下放一个verb_noun.md即可命名如install_chat_model.md、upgrade_backend.md首行写# Skill: Title Case 描述步骤编号工具名用反引号精确引用若技能会改动状态提醒 LLM 先与用户确认。文件会被//go:embed自动收集并按字典序拼进系统提示不需要任何 Go 改动。几条值得沿用的代码约定工具名一律引用tools.go的Tool*常量杜绝魔法字符串启停/固定动作使用modeladmin.Action类型的ActionEnable/ActionDisable/ActionPin/ActionUnpinhttpapi.Client的错误判断用errors.Is(err, ErrHTTPNotFound)而非字符串包含从 inproc client 向GalleryService.ModelGalleryChannel/BackendGalleryChannel发消息必须 selectctx.Done()以防取消的补全会泄漏 goroutine模型配置 YAML 落盘走modeladmin.writeFileAtomic临时文件 os.Rename因为os.WriteFile在崩溃截断时会损坏模型MCP 服务器生命周期必须向signals.RegisterGracefulTerminationHandler注册Close()。分布式模式下的边界内存 MCP 服务器只跑在 head 节点聊天处理器所在处。inproc.Client所包的服务本身是分布式感知的——GalleryService会与 worker 协调、ListNodes读取 NATS 填充的注册表MCP 工具不做 NATS 路由管理面就在 head 上仅此而已。十、小结LocalAI Assistant 的价值在于把 LocalAI 的管理 API 收敛成“管理员可以直接对话的 MCP 工具面”进程内形态让管理员在聊天里完成安装、删除、配置与后端升级stdio 形态把同一套工具输出到任意 MCP 宿主实现远程管理安全上由 UI 隐藏、请求时角色再校验、纯内存传输、提示词强制确认四层共同兜底扩展上则靠 REST 端点、LocalAIClient双实现与 skill 配方三层同步的清晰约定保持演进可控。对于希望让“AI 管理 AI”的运维与开发场景这是一个可以直接照做的设计范式。【免费下载链接】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），仅供参考
LocalAI Assistant：用自然语言聊天管理 LocalAI 的管理型 MCP 助手实战指南
LocalAI Assistant用自然语言聊天管理 LocalAI 的管理型 MCP 助手实战指南【免费下载链接】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 Assistant 是 LocalAI 内置的“管理员专用聊天模式”当一个聊天会话开启该模式后对话会被接入一个运行在进程内的 MCPModel Context Protocol服务器该服务器把 LocalAI 自身的安装模型、管理后端、编辑模型配置、查看系统状态等管理操作全部封装成 MCP 工具管理员只需“说话”即可完成管理全程无需 REST 调用、无需手写 YAML。本文以 docs/content/features/localai-assistant.md 为骨架结合pkg/mcp/localaitools/、core/http/endpoints/mcp/、core/cli/等源码实现从启用方式、安全模型、工具清单、独立 stdio 部署到二次开发完整讲解读完后你既能上手使用也能理解其底层机制并自行扩展。一、功能定位一种“可对话的管理员入口”LocalAI Assistant 本质上是 LocalAI 管理面admin/management surface的MCP 化封装。它区别于普通聊天的是三个特征仅面向管理员admin-only非管理员在界面上看不到开启入口聊天处理器也会在请求时刻二次校验管理员角色。不经过 HTTP 回环MCP 服务器直接跑在 LocalAI 进程内通过配对的net.Pipe()内存传输与聊天会话相连没有 localhost 回环端口、没有伪造的管理 API Key、没有额外的 TCP socket。两种运行形态共享同一套代码进程内in-process管理员在聊天 UI 中以metadata.localai_assistanttrue开启后聊天处理器把内存 MCP 服务器注入会话LLM 通过“聊天”即可安装模型、管理后端、编辑模型配置。独立 stdiostandalone通过local-ai mcp-server子命令把同一套管理工具以 stdio MCP 服务器形式对外提供可指向任意远程 LocalAI HTTP API如从桌面 MCP 客户端、Cursor、mcphost中远程操作 LocalAI。官方包文档在 pkg/mcp/localaitools/doc.go 中明确说明了这两种用法并指出“工具处理器与内嵌的技能提示skill prompts只面向LocalAIClient接口与底层传输/实现完全无关”。core/http/endpoints/mcp/localai_assistant.go中更进一步解释了为什么用一个进程级 holder 而非每次请求都建一对传输MCP 服务器在请求之间是无状态的复用同一对net.Pipe()与同一个LocalToolExecutor可以省掉反复建连与重复枚举工具的消耗。二、核心架构一次封装、两处复用2.1 包结构与目录职责管理 MCP 服务器整体位于公共 Go 包pkg/mcp/localaitools/.agents/localai-assistant-mcp.md中的“File map”给出了权威目录映射文件/目录职责client.goLocalAIClient接口定义与 DTO 注册表dto.go两个 client 实现共用的 JSON 标签 DTO不允许暴露裸 service 类型server.goNewServer(client, opts)—— 构建并注册全部工具的 MCP 服务器tools.goTool*工具名常量单一事实来源禁止散落裸字符串tools_*.go按功能分组的工具注册models/backends/config/system/state/scheduling/branding/voice_profiles/usage/pii/middleware/aliasesprompts.go//go:embed加载器 SystemPrompt(opts)系统提示组装prompts/*.md角色00_role.md、安全规则10_safety.md、工具目录20_tools.mdprompts/skills/*.md技能配方教 LLM“怎么干活”的 markdown按字典序自动拼入系统提示inproc/client.go进程内LocalAIClient直接调用 service不走 HTTP 回环httpapi/client.go走 REST 的LocalAIClient供独立 CLI / 远程实例使用2.2 服务器构建与可选参数pkg/mcp/localaitools/server.go 中Options提供三个开关DisableMutating bool为true时跳过所有会改动服务端状态的工具注册独立 CLI 的--read-only模式即依赖它。ServerName string覆盖 MCP 服务器对外通告的Implementation.Name默认localai-admin。ServerVersion string覆盖通告版本默认取internal.PrintableVersion()。NewServer依据传入的LocalAIClient依次调用registerModelTools、registerBackendTools、registerConfigTools、registerSystemTools、registerSchedulingTools、registerStateTools、registerBrandingTools、registerVoiceProfileTools、registerUsageTools、registerPIITools、registerMiddlewareTools、registerAliasTools等完成注册并把SystemPrompt(opts)作为mcp.ServerOptions.Instructions注入。2.3 系统提示的自动拼装机制pkg/mcp/localaitools/prompts.go 通过//go:embed prompts/*.md prompts/skills/*.md把全部 markdown 打进二进制随后SystemPrompt按字典序遍历并拼成一段带!-- file: ... --与# section: ...头注的完整系统提示。这意味着新增prompts/skills/xxx.md无需任何 Go 改动即会自动生效每一节都标注来源文件名方便追溯“LLM 正在引用哪个技能”。2.4 为什么用两个 client 而不是“自连一次”.agents/localai-assistant-mcp.md的 “Why two clients” 一节给出了直白理由进程内模式若走 HTTP 回环LocalAI 需要为“向自己认证”铸造一个合成管理 API Key并且每次工具派发都要双重序列化还会丢失进程内通道例如GalleryService.ModelGalleryChannel用于流式上报安装进度。因此进程内用inproc.Client直接调 service独立 CLI 面对远程实例只能用httpapi.Client走 REST。二者实现同一LocalAIClient接口测试层通过 parity_test.go 保持输出等价。三、在聊天中启用 Assistant实战步骤按官方文档启用流程如下以admin用户身份打开聊天 UI并在模型选择器中选择一个支持聊天的模型。头部出现Manage开关——把它打开聊天标题旁即显示Manage mode徽标。界面上会出现一批“起手提问”快捷 chips例如“What is installed?”“Install a chat model”“Show system status”“Update a backend”首页还会暴露一个Manage by chatCTA点击后直接打开一个已处于 Manage 模式的全新聊天会话。开启后即可尝试自然语言指令例如Install Qwen 3 chat助理会按技能流程执行先在模型库gallery中搜索、列出候选、请你在编号列表中挑选、摘要将要执行的安装动作并等待你的确认然后才调用install_model安装期间它会轮询进度并向你汇报最终结果。从实现角度聊天请求通过metadata.localai_assistanttrue这个元数据声明“本会话走助理通道”该标记由core/http/endpoints/openai/chat_assistant_gate.go的requireAssistantAccess校验见下文安全模型进程内的 MCP 服务器会话则由 core/http/endpoints/mcp/localai_assistant.go 中的LocalAIAssistantHolder持有工具列表在应用启动时预发现首个聊天请求不必再付一次list_tools往返开销。四、关闭特性关闭 LocalAI Assistant 有两种方式粒度不同运行期关闭在Settings → LocalAI Assistant中关掉开关立即生效、无需重启。启动期硬关闭设置环境变量后启动LOCALAI_DISABLE_ASSISTANTtrue local-ai run关闭后的行为聊天处理器会拒绝携带metadata.localai_assistanttrue的请求并返回503界面上的 Manage 开关被隐藏。这与源码中的处理一致LocalAIAssistantHolder在DisableLocalAIAssistant为真或初始化失败时Executor()返回空的LocalToolExecutor、HasTools()为false聊天处理器据此判定“功能不可用”。五、安全模型层层防护官方文档与源码共同确认了这套安全模型界面层Manage 开关对非管理员用户隐藏聊天 UI 由前端按角色渲染。请求层纵深防御即便认证配置被设为“跳过助理功能门禁”聊天处理器仍会在请求时刻重新校验管理员角色。core/http/endpoints/openai/chat_assistant_gate.go 的实现如下当认证开启时取出当前用户若用户不存在或user.Role ! auth.RoleAdmin直接返回403 localai_assistant requires admin只有认证整体被关闭时该校验才是 no-op此时操作者选择信任所有调用方。网络层MCP 服务器跑在进程内使用net.Pipe()配对传输不存在 localhost 回环、合成 API Key 或额外 TCP socket天然没有可被外部探测的管理端口。行为层提示词强制确认所有变更型工具install_model、delete_model、edit_model_config、upgrade_backend等都由系统提示中的安全规则约束要求 LLM 在调用前先向用户明确说明动作并获得确认代码层没有额外的 preview/apply 两阶段。.agents/localai-assistant-mcp.md明确说这是 KISS 设计选择新增变更型工具时不要加 Go 代码层面的确认逻辑只需把工具名登记进prompts/10_safety.md规则 1 即可。系统提示中完整的安全规则见 pkg/mcp/localaitools/prompts/10_safety.md共 5 条核心纪律变更前确认列出所有受约束工具调用前须用平实语言说明“做什么哪个工具、哪个目标、哪些参数”并等待用户下一轮的显式确认“Yes”“do it”“go ahead”“proceed”均算确认其余不算。变更前消歧请求含糊多个 gallery 候选、同一模型多个已装版本、后端存在变体时把候选列成编号清单请用户先选择。原样呈现工具错误工具返回错误时把错误原文放进 fenced code block 引用给用户不重试、不改写等待用户指示。绝不编造标识符只使用本对话中工具返回过的模型名、gallery 名、后端名与 job ID没有就先调用gallery_search/list_*工具。轮询上限轮询get_job_status时在processed: true、cancelled: true或已轮询 30 次三者中先到者停止并始终向用户总结最终结果。规则 1 的工具名单在 Go 侧由 tools.go 的mutatingToolNames常量维护prompts_test.go会自动校验名单与提示词保持一致避免“改工具忘记改安全提示”的漂移。六、独立 stdio MCP 服务器外部远程管理同一套管理工具面可以以 stdio MCP 服务器形式指向任意 LocalAI HTTP API# 完整模式连接远程实例并携带管理员 key local-ai mcp-server --target http://remote.localai:8080 --api-key admin-key # 只读模式跳过所有变更型工具的注册安装/删除/编辑/升级等均不出现 local-ai mcp-server --target http://remote.localai:8080 --read-only这样就能把 LocalAI 管理能力接入 Claude Desktop、Cursor 或任何 MCP host。其工具目录与进程内变体完全一致——两者共用localaitools.NewServer与同一套 skill prompts只是LocalAIClient实现不同。CLI 结构core/cli/mcp_server.go提供了三个可控参数并支持以环境变量覆盖参数环境变量默认值说明--targetLOCALAI_MCP_TARGEThttp://localhost:8080目标 LocalAI 基础 URL为空时报错退出--api-keyLOCALAI_API_KEY空访问目标 LocalAI 的 Bearer API Key--read-only——false为真时通过Options.DisableMutating跳过全部变更型工具注册进程内部注意点stdio 模式下 stdout 专供 JSON-RPC其它日志只能走 stderr同时使用signal.NotifyContext监听 SIGINT/SIGTERM以便宿主 Ctrl-C 或kill -TERM时给srv.Run机会排空进行中的调用。七、工具目录全览7.1 官方文档的完整清单必须原样掌握只读工具gallery_search、list_installed_models、list_galleries、list_backends、list_known_backends、get_job_status、get_model_config、vram_estimate、system_info、list_nodes。变更型工具依据助手安全提示须经用户确认install_model、import_model_uri、delete_model、install_backend、upgrade_backend、edit_model_config、reload_models、toggle_model_state、toggle_model_pinned。7.2 源码注册的完整目录比文档更全的现行事实从 tools.go 的常量与 prompts/20_tools.md 的“策展式”描述看实际注册的工具面比 feature 文档列举的更广二者并不冲突——feature 文档是入门入口tools.go是运行时真相。整理为下表类别工具一句话说明只读gallery_search在已配置的模型库中搜索可安装模型只读list_installed_models列出已装模型支持capability过滤chat/embed/image等只读list_galleries/list_backends/list_known_backends列出已配置 gallery / 已装后端 / 可从后端库安装的后端只读get_job_status按 job id 轮询安装/删除/升级任务状态只读get_model_config读取已装模型的 YAML/JSON 配置只读vram_estimate/system_info/list_nodes显存估算 / LocalAI 版本与路径等系统信息 / 分布式联邦节点列表只读list_scheduling/get_scheduling分布式按模型调度配置的列表与单条读取只读list_voice_profiles/get_branding语音克隆档案列表 / 实例名与标语读取只读get_usage_stats/get_pii_events/get_middleware_status用量聚合 / PII 过滤事件 / 中间件状态只读探查只读get_router_decisions/get_router_corpus_stats/list_aliasesKNN 路由决策与语料统计只返回计数与标签绝不返回示例文本/ 别名清单变更install_model/import_model_uri从 gallery 安装模型返回 job id用get_job_status轮询/ 从任意 URIHuggingFace、OCI、http(s)、file://导入多后端适用时返回ambiguous_backend需以backend_preference再次调用变更delete_model/edit_model_config/reload_models删除模型 / 深合并 JSON 补丁到已装模型配置 / 从磁盘重载全部模型配置变更load_model预载模型进内存消除首请求冷启动对实时管线模型会加载全部子模型VAD、转写、LLM、TTS 等变更install_backend/upgrade_backend安装后端 / 按名升级已装后端变更toggle_model_state/toggle_model_pinned启停模型action:enable/disable/ 固定与取消固定action:pin/unpin变更set_branding/set_alias修改实例名或标语 / 增改删模型别名变更seed_router_corpus/clear_router_corpus向 KNN 路由语料加入带标签样本 / 永久清空语料与活动索引变更create_voice_profile/delete_voice_profile保存经同意的 base64 PCM-WAV 参考音与精确转写供 TTS 复用 / 按 UUID 永久删除档案变更set_node_vram_budget/set_scheduling/delete_scheduling设置/清除联邦节点 VRAM 预算覆盖 / 增改/删除分布式按模型调度配置注意一个容易踩的细节.agents/localai-assistant-mcp.md的代码约定list_installed_models的 capability 过滤用的是capability.go中类型化的Capability常量只接受规范值如CapabilityEmbeddings不存在embed/embedding互为别名这类宽松匹配。八、技能配方SkillsLLM 的操作手册除角色与安全规则外prompts/skills/下现有 8 个按“动词_名词.md”命名的技能文件configure_branding.md # 配置品牌实例名/标语 edit_model_config.md # 修改模型配置 import_model_from_uri.md # 从 URI 导入模型 install_chat_model.md # 安装聊天模型含冷启动引导 manage_distributed_scheduling.md manage_router_corpus.md system_status.md # 汇报系统状态 upgrade_backend.md # 升级后端以 install_chat_model.md 为例可见技能配方如何“把一次完整安装拆成可验证的步骤序列”用用户的查询调用gallery_search用户明确要聊天模型时加tag: chat以编号列表展示前几名结果含名称、gallery、简介与许可无匹配就说明并询问是否放宽搜索等待用户挑选摘要将要安装的gallery/name如“我将安装gallery/name确认吗”并等待确认确认后以gallery_name与model_name调用install_modelvariant留空让 LocalAI 依据本机引擎与空闲内存自动挑选能跑的最大构建仅当用户点名具体构建如“Q8 那个”时才精确填写列表中的名字——写错名字会导致安装失败而不是回退到自动选择用返回的 job id 轮询get_job_status报告有意义的进度变化每约 10%–20%外加完成processed: true且无错误后调用reload_models再用capability: chat的list_installed_models确认模型已可见告知用户模型已就绪以及聊天补全接口中应填写的model名称。该文件还要求install_model失败时原样呈现错误并询问“重试 / 换模型 / 放弃”。这些配方通过//go:embed自动拼入系统提示字典序、带来源头注LLM 在收到用户请求时据此决定调用哪些工具、问什么问题、如何收尾。九、为 Assistant 新增工具或技能扩展指南.agents/localai-assistant-mcp.md给出了完整的三层同步契约与新增检查清单面向所有“会碰 LocalAI 管理面”的人人类或 AI Agent“三层必须同步”当你改动 LocalAI 管理面时以下三层必须保持一致否则聊天管理端看不到新功能——REST 端点core/http/endpoints/localai/*.go并在core/http/routes/localai.go中以auth.RequireAdmin()门禁MCP 工具注册在pkg/mcp/localaitools/tools_*.go注册工具 在client.go的LocalAIClient接口加方法 在inproc/client.go与httpapi/client.go各加实现技能提示在prompts/skills/下新增/更新 markdown教 LLM 何时调用该工具、先问用户什么、出错怎么办。新增管理端点的检查清单要点REST 端点存在且以auth.RequireAdmin()门禁LocalAIClient接口含覆盖新操作的 methodDTO 加进dto.goJSON 打标签绝不暴露裸 service 类型inproc/client.go直接调 service不走 HTTP 回环httpapi/client.go调对应 REST 端点在合适的tools_*.go注册工具变更型工具须在描述中引用安全规则 1变更型工具须保证Options{DisableMutating: true}会跳过它参考tools_models.go的模式更新/新增prompts/skills/下的技能文件测试补齐把工具名加进 server_test.go 的expectedFullCatalog只读则加进expectedReadOnlyCatalog把派发用例加进TestEachToolDispatchesToClient并在httpapi/client_test.go覆盖新 HTTP 路径。新增技能配方无需新工具在prompts/skills/下放一个verb_noun.md即可命名如install_chat_model.md、upgrade_backend.md首行写# Skill: Title Case 描述步骤编号工具名用反引号精确引用若技能会改动状态提醒 LLM 先与用户确认。文件会被//go:embed自动收集并按字典序拼进系统提示不需要任何 Go 改动。几条值得沿用的代码约定工具名一律引用tools.go的Tool*常量杜绝魔法字符串启停/固定动作使用modeladmin.Action类型的ActionEnable/ActionDisable/ActionPin/ActionUnpinhttpapi.Client的错误判断用errors.Is(err, ErrHTTPNotFound)而非字符串包含从 inproc client 向GalleryService.ModelGalleryChannel/BackendGalleryChannel发消息必须 selectctx.Done()以防取消的补全会泄漏 goroutine模型配置 YAML 落盘走modeladmin.writeFileAtomic临时文件 os.Rename因为os.WriteFile在崩溃截断时会损坏模型MCP 服务器生命周期必须向signals.RegisterGracefulTerminationHandler注册Close()。分布式模式下的边界内存 MCP 服务器只跑在 head 节点聊天处理器所在处。inproc.Client所包的服务本身是分布式感知的——GalleryService会与 worker 协调、ListNodes读取 NATS 填充的注册表MCP 工具不做 NATS 路由管理面就在 head 上仅此而已。十、小结LocalAI Assistant 的价值在于把 LocalAI 的管理 API 收敛成“管理员可以直接对话的 MCP 工具面”进程内形态让管理员在聊天里完成安装、删除、配置与后端升级stdio 形态把同一套工具输出到任意 MCP 宿主实现远程管理安全上由 UI 隐藏、请求时角色再校验、纯内存传输、提示词强制确认四层共同兜底扩展上则靠 REST 端点、LocalAIClient双实现与 skill 配方三层同步的清晰约定保持演进可控。对于希望让“AI 管理 AI”的运维与开发场景这是一个可以直接照做的设计范式。【免费下载链接】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），仅供参考
