LocalAI 快速上手指南从容器启动、模型安装到 OpenAI 兼容 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 官方 快速上手指南 的中文深度解读。LocalAI 是一款免费开源的 OpenAI/Anthropic 兼容 REST API 服务可在消费级硬件上本地运行 LLM、图像生成、音频生成等模型不强制要求 GPU。读完本文你将掌握完整的实战闭环如何用 Docker 启动服务含 GPU 镜像选型、如何通过 Web 界面或local-ai run命令行安装并加载第一个模型、如何使用 curl 完成/v1/chat/completions的首次调用以及如何在此基础上探索内置 AI Agent 与分布式扩展能力。安全提醒远程暴露前的访问控制如果 LocalAI 需要被远程访问而非仅在本机回环地址使用务必对 API 端点做充分的访问保护。项目提供了两种渐进式方案详见 core/cli/run.go 中对应 CLI 参数的实现简单 API Key以LOCALAI_API_KEYyour-key启动即可拦截未授权请求。注意 API Key 拥有全部管理权限没有角色分离适合个人或信任环境。完整用户认证以LOCALAI_AUTHtrue启动获得多用户支持包括 admin/user 角色划分、OAuthGitHub / OIDC登录、按用户发放 API Key 以及用量追踪。详细配置参见 认证与授权指南。从源码看LocalAI 还内置了“公共地址强制鉴权”保护当监听地址是公网地址或通配符绑定的主机存在公网网卡且未配置任何认证时服务会拒绝启动除非显式传入--allow-insecure-public-bind见 run.go这为误把服务暴露到公网提供了最后一道防线。启动 LocalAI方式一Docker 容器启动推荐假设你已经完成了 安装指南 中的任一种安装。Docker 方式只需一条命令docker run -p 8080:8080 --name local-ai -ti localai/localai:latest容器启动后API 服务默认监听在:8080对应源码中Address参数的默认值:8080见 core/cli/run.go。根据硬件选择 GPU 镜像需要 GPU 加速时按硬件选对应镜像标签Docker 与 Podman 均支持完整矩阵参见 容器镜像参考硬件Docker 镜像仅 CPUlocalai/localai:latestNVIDIA CUDAlocalai/localai:latest-gpu-nvidia-cuda-12AMD (ROCm)localai/localai:latest-gpu-hipblasIntel GPUlocalai/localai:latest-gpu-intelVulkanlocalai/localai:latest-gpu-vulkan对应启动命令要点NVIDIA追加--gpus all。例如docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-12NVIDIA 驱动较新Container Toolkit ≥1.14时推荐使用 CDI 配置--device nvidia.com/gpuall。AMD / Intel / Vulkan按需追加--device参数。AMD 通常需要--device/dev/kfd --device/dev/dri --group-addvideo。若要在升级镜像后保留已安装的模型、后端与数据务必把容器内四个路径挂载出来/models模型文件、/backends推理后端、/configurationapi_keys.json、runtime_settings.json 等动态配置、/dataagent 状态、任务、任务数据等持久化内容容器内路径必须固定为这四个目录名。方式二直接运行二进制安装本地二进制后可在任意终端直接执行local-ai系列命令所有 CLI 参数都对应同名环境变量kebab-case 命名约定完整参数列表可通过local-ai run --help查看。使用内置 Web 界面完成首次聊天LocalAI 自带开箱即用的Web 用户界面源码层面对应--disable-webui开关默认启用无需额外部署前端。浏览器打开http://localhost:8080即可Chat与任意已安装模型对话Models 页面浏览、安装与管理模型生成图像、音频等内容创建并管理 AI Agent支持 MCP 工具监控系统资源与已加载模型配置 GPU 加速等运行设置。完成第一次聊天三步打开Models → Explore搜索qwen3-4b在其条目上点击Install并等待下载完成。qwen3-4b是一个轻量、对 CPU 友好的 Qwen3 模型同时支持工具调用tool calling因此后续可直接复用它完成 构建你的第一个 Agent 的演练。该条目在仓库模型目录中确实存在见 gallery/index.yaml官方 Gallery 索引会引导下载来自 Hugging Face 的 Qwen3-4B GGUF 权重。打开Chat页面在模型下拉框中选择qwen3-4b输入消息并发送通常几秒内即可收到回复。编辑已保存消息如果之前发送的 prompt 或响应有误无需让模型重新生成将鼠标悬停在已保存的消息上并选择Edit即可就地编辑。Save会更新该会话的本地历史记录Cancel则丢弃草稿。从命令行下载模型启动 LocalAI 时无论 Docker 还是 CLI都可以把要安装的模型作为参数传入服务会在 API 启动前自动完成安装local-ai run qwen3-4b local-ai run huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf local-ai run ollama://gemma:2b local-ai run https://gist.githubusercontent.com/.../phi-2.yaml local-ai run oci://localai/phi-2:latest可以看到local-ai run支持多种模型来源 URIGallery 模型名、huggingface://直接权重地址、ollama://、远程模型 YAML 配置、oci://OCI 镜像。这一逻辑在 core/cli/run.go 中被建模为ModelArgs可附加多个位置参数并在 core/cli/models.go 中通过 URI 类型判断决定走 Gallery 查找还是 OCI 拉取路径。用 models 子命令管理模型local-ai models list # 列出 Gallery 中可用的模型 local-ai models install name # 安装指定模型其中models list会遍历已配置 Gallery已安装条目以* name (installed)标注实现见 core/cli/models.gomodels install会在下载前执行一次尽力而为的安全扫描DisablePredownloadScan默认关闭即默认启用扫描见 core/cli/models.go。自动后端检测从 Gallery 或 YAML 安装模型时LocalAI 会自动探测本机 GPU 能力NVIDIA / AMD / Intel并下载对应推理后端无需手工指定后端类型。高级配置见 GPU 加速 文档中的 “Automatic Backend Detection” 一节。完整的启动参数可运行local-ai run --help或查阅 Linux 安装指南。使用 OpenAI 兼容 APILocalAI 对外暴露OpenAI 兼容 REST API任何 OpenAI SDK 或客户端只要把 base URL 指向http://localhost:8080即可无缝接入。最直接的验证方式是 curlcurl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-4b, messages: [{role: user, content: Hello!}] }除 OpenAI Chat Completions 外LocalAI 还提供Anthropic Messages API/v1/messages使 Anthropic 官方 SDK 也能直接对接Open Responses APIOllama 兼容端点/api/*由--ollama-api-root-endpoint控制是否占用根路径端点本身始终可用见 core/cli/run.go等。各端点的完整调用示例参见 Try it out。在仓库中请求/响应结构集中在 core/schema如 openai.go、anthropic.go、openresponses.go方便在切换协议时对照字段。内置 AI Agent 平台LocalAI 内置 AI Agent 平台原生支持Model Context Protocol (MCP)。通过 Web 界面即可创建能调用工具、浏览网页、执行代码、对接外部服务的 Agent无需额外安装任何组件——Agent 就是 LocalAI 的一部分Agent 池在 HTTP 服务就绪后自动启动见 core/cli/run.go。起步步骤安装一个支持工具调用的模型主流现代 LLM 基本都支持在 Web 界面打开Agents页面新建 Agent为其配置工具与系统提示词system prompt开始对话Agent 会自主调用工具完成任务。分步完整教程见 构建你的第一个 Agent。若想了解更多 MCP 能力可参考 MCP 特性文档 与源码目录 pkg/mcp/localaitools。扩展到分布式模式生产部署或算力不足时LocalAI 支持横向扩展的分布式模式主要有三类能力分布式节点Distributed nodesGPU 工作节点自行注册到前端协调器实现按需调度P2P 联邦P2P federation多实例互联做负载均衡推理--p2p开关见 core/cli/run.go模型分片Model sharding将大模型拆分到多台机器上共同加载。分布式模式涉及的相关配置在 core/cli/run.go 中集中声明需 PostgreSQL NATS包含注册令牌、节点心跳、前缀缓存路由等大量调优项。可视化的管理入口在 Web 界面的Nodes页面详细搭建步骤见 分布式推理文档。下一步还可以做什么LocalAI 的能力远不止文本聊天还支持视频生成、声音克隆、Embedding、图像理解等。官方文档建议继续探索容器镜像参考全部 Docker/Podman 镜像与持久化挂载矩阵API 端点试玩所有兼容端点的请求示例全部特性清单文本生成、图像生成、TTS/ASR、语音识别等官方 Model Gallery模型下载源手动运行模型不用 Gallery、直接以 YAML 加载模型的完整配置方式从源码构建源码见 cmd/local-ai/main.go入口通过 Kong 解析全部 CLI 参数并调用Run启动应用仓库自带 examples 示例 可参考。通过本文的路径——容器启动 → Web/CLI 安装模型 → curl 调通首个/v1/chat/completions——你就已经完整走通了 LocalAI 的本地推理主线剩余的一切Agent、分布式、多模态都是在这条主线上按需叠加的进阶能力。【免费下载链接】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），仅供参考