如何用 LocalAI 的模型别名让现有模型以 gpt-4 等自定义名称对外提供服务【免费下载链接】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如果你的客户端代码写死了gpt-4这样的模型名而你希望请求实际由 LocalAI 上的本地模型处理又不想改动任何客户端配置可以用 LocalAI 的模型别名Model Aliases功能。模型别名是一个指向另一个已配置模型的重定向名字把gpt-4声明为my-llama-3的别名后所有调用gpt-4的客户端都会由my-llama-3应答客户端保持原有模型名不变实际应答方由服务端控制。本文适用环境LocalAI 已安装并可启动Docker 或 CLI 方式均可默认端口 8080且已经装好一个目标模型。别名的完整行为规则见 model-aliases 文档。别名机制的边界先看清楚在动手之前了解文档明确给出的几条规则可以避免大部分配置错误目标模型必须是一个已存在的、非别名的、启用状态的模型。别名不能指向缺失的模型、被禁用的模型或另一个别名不允许链式别名。别名是 1:1 的一个别名恰好映射一个目标。目标可以在线切换编辑配置文件、调用 API、使用 UI、或询问助手都可以无需重启 LocalAI。gpt-4和目标模型my-llama-3会同时出现在GET /v1/models的列表中。响应回显请求的别名调用gpt-4时响应里的model字段返回gpt-4而不是目标名。用量统计记录两端请求的是gpt-4实际应答的是my-llama-3。别名对所有模态生效chat、embeddings、audio、images 等。前置条件启动 LocalAI 并准备模型目录别名配置以 YAML 文件形式放在模型目录中所以先要有一个挂载或固定的模型目录。以 Docker 方式为例Setting Up Models 文档中的启动方式mkdir models docker run -p 8080:8080 -v $PWD/models:/models -ti --rm localai/localai:latest --models-path /models --context-size 700 --threads 4其中-v $PWD/models:/models把宿主机上的models/目录挂进容器--models-path /models告诉 LocalAI 模型目录位置CLI 下对应环境变量MODELS_PATH。后续创建的别名文件就放在宿主机的models/里容器内对应/models/。如果你已经用别的方式启动了 LocalAI如local-ai run只需确认目标模型已安装且启用。Quickstart 覆盖了 Docker、CLI 等启动方式GPU 用户可参考其中的镜像选择表。先确认目标模型可用curl http://localhost:8080/v1/models在返回的模型列表中找到你要对外暴露的那个模型名下文的my-llama-3是文档示例值替换为你实际的模型名。声明别名一个两行的 YAML在你的模型目录中创建一个最小配置文件示例文件名models/gpt-4.yaml文件名可自取name: gpt-4 alias: my-llama-3这就是全部配置name客户端调用的别名名文档示例用gpt-4替换为你客户端实际写死的名字alias真正应答请求的目标模型文档示例用my-llama-3替换为你上一步确认的已安装模型名。两个值都是文档中的示例值必须按上面的说明替换成你自己的名字。注意别名配置里只有这两个键不能带backend或parameters.model原因见下文“不能把真实模型改造成别名”一节。验证别名是否生效按顺序做两个检查确认两个名字都在模型列表中curl http://localhost:8080/v1/models按文档行为gpt-4和目标模型my-llama-3应该都出现。用别名发起一次真实的推理请求沿用 Quickstart 中 OpenAI 兼容接口的调用形式把model换成你的别名curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4, messages: [{role: user, content: Hello!}] }判断依据请求能正常返回模型应答且响应中的model字段回显gpt-4而不是目标模型名。同时可以用别名列表接口核对服务端当前登记了哪些别名curl http://localhost:8080/api/aliases不重启切换别名的目标模型别名的目标支持在线更换live swap有四种入口任选其一即可均无需重启直接编辑模型目录里的别名 YAML把alias指向新目标REST APIPATCH /api/models/config-json/:nameWeb UI下节说明询问 LocalAI Assistant。这是把别名当作“稳定槽位”使用的核心客户端永远调用gpt-4你随时更换它背后实际运行的模型。用 Web UI、REST API 或 Assistant/MCP 管理别名除了直接写文件文档提供了三种管理界面支持创建、更换目标、删除别名。Web UI打开 http://localhost:8080 的Add Model页面选择Alias / Routing模板填好名字别名和目标实际模型即可。要把一个已有别名重新指向新目标编辑该别名并修改 target。REST API创建POST /models/import更换目标PATCH /api/models/config-json/:name列出所有别名GET /api/aliases删除POST /models/delete/:nameAssistant 与 MCPLocalAI Assistant以及 MCP server把同样的一组操作暴露为工具set_alias、list_aliases和delete_model。为什么不能把现有真实模型直接改成别名这是文档用专门提示框强调的一条限制无法把一个已有的真实模型变成别名。如果对一个已经是真实非别名模型的名称执行set_alias或对PATCH /api/models/config-json/:name发起同类请求请求会被拒绝。原因是别名必须是纯重定向不能携带backend或parameters.model而真实模型必须携带这两者把alias合并进真实模型的配置会产生无效配置校验会报alias config ... must not set backend or parameters.model并拒绝。这是有意为之的设计防止误操作覆盖掉一个正在对外服务的模型。正确做法新增别名时用一个新名字指向目标模型不要复用现有模型的名字把已有的别名重新指向另一个目标则完全支持这正是上面的在线切换路径——别名配置本身没有 backend换目标后仍是合法的纯重定向。可选分布式模式下把别名用作部署槽位如果你运行的是 distributed mode别名还可以承载调度规则。POST /api/nodes/scheduling接受别名的model_name规则随后管辖该别名指向的模型curl -X POST http://frontend:8080/api/nodes/scheduling \ -H Content-Type: application/json \ -d {model_name: production, node_selector: {tier: gpu}, min_replicas: 2}示例中的frontend:8080为文档原文的地址写法。重新指向production后放置策略跟着走别名因此成为一个内容可随时替换的稳定槽位。由于副本replica被所有解析到它的名字共享同一时刻只允许一条规则管辖某个模型。该节的更多细节见 distributed-mode 文档 的 “Scheduling a model alias” 小节。单节点本地使用不涉及分布式调度可以跳过本节。限制别名是静态的 1:1 重定向它解决的是“名字到模型”的映射问题。如果你的需求是在多个下游模型之间做基于分类器或负载均衡的自动选择文档给出的对应方案是 Middleware 功能中的 intelligent router而不是别名。【免费下载链接】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），仅供参考 
长河君 · 2026/9/13 20:17:59 · 阅读 1.2k 如何用 LocalAI 的模型别名让现有模型以 gpt-4 等自定义名称对外提供服务？
如何用 LocalAI 的模型别名让现有模型以 gpt-4 等自定义名称对外提供服务【免费下载链接】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如果你的客户端代码写死了gpt-4这样的模型名而你希望请求实际由 LocalAI 上的本地模型处理又不想改动任何客户端配置可以用 LocalAI 的模型别名Model Aliases功能。模型别名是一个指向另一个已配置模型的重定向名字把gpt-4声明为my-llama-3的别名后所有调用gpt-4的客户端都会由my-llama-3应答客户端保持原有模型名不变实际应答方由服务端控制。本文适用环境LocalAI 已安装并可启动Docker 或 CLI 方式均可默认端口 8080且已经装好一个目标模型。别名的完整行为规则见 model-aliases 文档。别名机制的边界先看清楚在动手之前了解文档明确给出的几条规则可以避免大部分配置错误目标模型必须是一个已存在的、非别名的、启用状态的模型。别名不能指向缺失的模型、被禁用的模型或另一个别名不允许链式别名。别名是 1:1 的一个别名恰好映射一个目标。目标可以在线切换编辑配置文件、调用 API、使用 UI、或询问助手都可以无需重启 LocalAI。gpt-4和目标模型my-llama-3会同时出现在GET /v1/models的列表中。响应回显请求的别名调用gpt-4时响应里的model字段返回gpt-4而不是目标名。用量统计记录两端请求的是gpt-4实际应答的是my-llama-3。别名对所有模态生效chat、embeddings、audio、images 等。前置条件启动 LocalAI 并准备模型目录别名配置以 YAML 文件形式放在模型目录中所以先要有一个挂载或固定的模型目录。以 Docker 方式为例Setting Up Models 文档中的启动方式mkdir models docker run -p 8080:8080 -v $PWD/models:/models -ti --rm localai/localai:latest --models-path /models --context-size 700 --threads 4其中-v $PWD/models:/models把宿主机上的models/目录挂进容器--models-path /models告诉 LocalAI 模型目录位置CLI 下对应环境变量MODELS_PATH。后续创建的别名文件就放在宿主机的models/里容器内对应/models/。如果你已经用别的方式启动了 LocalAI如local-ai run只需确认目标模型已安装且启用。Quickstart 覆盖了 Docker、CLI 等启动方式GPU 用户可参考其中的镜像选择表。先确认目标模型可用curl http://localhost:8080/v1/models在返回的模型列表中找到你要对外暴露的那个模型名下文的my-llama-3是文档示例值替换为你实际的模型名。声明别名一个两行的 YAML在你的模型目录中创建一个最小配置文件示例文件名models/gpt-4.yaml文件名可自取name: gpt-4 alias: my-llama-3这就是全部配置name客户端调用的别名名文档示例用gpt-4替换为你客户端实际写死的名字alias真正应答请求的目标模型文档示例用my-llama-3替换为你上一步确认的已安装模型名。两个值都是文档中的示例值必须按上面的说明替换成你自己的名字。注意别名配置里只有这两个键不能带backend或parameters.model原因见下文“不能把真实模型改造成别名”一节。验证别名是否生效按顺序做两个检查确认两个名字都在模型列表中curl http://localhost:8080/v1/models按文档行为gpt-4和目标模型my-llama-3应该都出现。用别名发起一次真实的推理请求沿用 Quickstart 中 OpenAI 兼容接口的调用形式把model换成你的别名curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4, messages: [{role: user, content: Hello!}] }判断依据请求能正常返回模型应答且响应中的model字段回显gpt-4而不是目标模型名。同时可以用别名列表接口核对服务端当前登记了哪些别名curl http://localhost:8080/api/aliases不重启切换别名的目标模型别名的目标支持在线更换live swap有四种入口任选其一即可均无需重启直接编辑模型目录里的别名 YAML把alias指向新目标REST APIPATCH /api/models/config-json/:nameWeb UI下节说明询问 LocalAI Assistant。这是把别名当作“稳定槽位”使用的核心客户端永远调用gpt-4你随时更换它背后实际运行的模型。用 Web UI、REST API 或 Assistant/MCP 管理别名除了直接写文件文档提供了三种管理界面支持创建、更换目标、删除别名。Web UI打开 http://localhost:8080 的Add Model页面选择Alias / Routing模板填好名字别名和目标实际模型即可。要把一个已有别名重新指向新目标编辑该别名并修改 target。REST API创建POST /models/import更换目标PATCH /api/models/config-json/:name列出所有别名GET /api/aliases删除POST /models/delete/:nameAssistant 与 MCPLocalAI Assistant以及 MCP server把同样的一组操作暴露为工具set_alias、list_aliases和delete_model。为什么不能把现有真实模型直接改成别名这是文档用专门提示框强调的一条限制无法把一个已有的真实模型变成别名。如果对一个已经是真实非别名模型的名称执行set_alias或对PATCH /api/models/config-json/:name发起同类请求请求会被拒绝。原因是别名必须是纯重定向不能携带backend或parameters.model而真实模型必须携带这两者把alias合并进真实模型的配置会产生无效配置校验会报alias config ... must not set backend or parameters.model并拒绝。这是有意为之的设计防止误操作覆盖掉一个正在对外服务的模型。正确做法新增别名时用一个新名字指向目标模型不要复用现有模型的名字把已有的别名重新指向另一个目标则完全支持这正是上面的在线切换路径——别名配置本身没有 backend换目标后仍是合法的纯重定向。可选分布式模式下把别名用作部署槽位如果你运行的是 distributed mode别名还可以承载调度规则。POST /api/nodes/scheduling接受别名的model_name规则随后管辖该别名指向的模型curl -X POST http://frontend:8080/api/nodes/scheduling \ -H Content-Type: application/json \ -d {model_name: production, node_selector: {tier: gpu}, min_replicas: 2}示例中的frontend:8080为文档原文的地址写法。重新指向production后放置策略跟着走别名因此成为一个内容可随时替换的稳定槽位。由于副本replica被所有解析到它的名字共享同一时刻只允许一条规则管辖某个模型。该节的更多细节见 distributed-mode 文档 的 “Scheduling a model alias” 小节。单节点本地使用不涉及分布式调度可以跳过本节。限制别名是静态的 1:1 重定向它解决的是“名字到模型”的映射问题。如果你的需求是在多个下游模型之间做基于分类器或负载均衡的自动选择文档给出的对应方案是 Middleware 功能中的 intelligent router而不是别名。【免费下载链接】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），仅供参考