本文详细阐述了 LocalAI 大模型推理服务框架的部署流程。内容包括环境准备、Docker 容器化安装、针对国内网络的 HuggingFace 镜像源配置、模型加载与 Prompt 模板设置。此外，提供了基于 Curl 和 Python 的 API 调用示例，并分析了常见网络问题及资源优化方案，旨在帮助开发者快速构建私有化大模型推理服务。
LocalAI 是一个开源的本地化 AI 模型推理框架，旨在提供与 OpenAI API 完全兼容的服务。它支持多种模型格式（如 GGUF），允许开发者在本地或私有服务器上快速部署大语言模型，无需依赖外部云服务，特别适合对数据隐私有要求或网络环境受限的场景。
相较于其他推理框架，LocalAI 的优势在于其容器化部署的便捷性以及对多模态任务的支持。本文将详细介绍如何在 Linux 服务器环境下，通过 Docker 一键部署 LocalAI，并解决国内网络环境下的模型下载问题，最后提供 API 调用的完整示例。
首先，从 GitHub 获取 LocalAI 的最新源代码：
git clone https://github.com/mudler/LocalAI
进入项目目录：
cd LocalAI
LocalAI 支持加载 Hugging Face 上的 GGUF 格式模型。由于国内网络限制，直接访问 huggingface.co 可能会失败，建议使用镜像站。
创建 models 目录并下载模型：
mkdir -p models
wget https://hf-mirror.com/TheBloke/Luna-AI-Llama2-Uncensored-GGUF/resolve/main/luna-ai-llama2-uncensored.Q4_0.gguf -O models/luna-ai-llama2
注意：如果 wget 命令不可用，可使用 curl 替代。
为了让模型更好地遵循指令，需要复制默认的提示词模板到 models 目录：
cp -rf prompt-templates/getting_started.tmpl models/luna-ai-llama2.tmpl
这将创建一个名为 luna-ai-llama2.tmpl 的文件，用于定义对话的系统提示。
使用官方提供的 aio-gpu 镜像启动服务。该镜像集成了文生文、图生文等多种能力。
docker run -tid \
--name local-ai \
-p 16080:8080 \
--gpus all \
-v /path/to/LocalAI/models:/models \
localai/localai:latest-aio-gpu-nvidia-cuda-12 \
--models-path /models
参数说明：
-tid: 后台运行，分配伪终端。--name local-ai: 容器名称。-p 16080:8080: 将宿主机的 16080 端口映射到容器的 8080 端口。--gpus all: 启用所有可用 GPU 资源。-v ...: 挂载宿主机模型目录到容器内，方便持久化管理。--models-path /models: 指定容器内模型加载路径。启动后，检查容器日志确认无报错：
docker logs local-ai
测试模型列表接口：
curl http://localhost:16080/v1/models
预期返回包含模型 ID 的 JSON 列表。
测试聊天接口：
curl http://localhost:16080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "luna-ai-llama2", "messages": [{"role": "user", "content": "Who are you?"}], "temperature": 0.9}'
对于无法科学上网的服务器，直接从 Hugging Face 拉取模型可能超时。LocalAI 提供了配置文件来修改下载源。
进入容器内的 models 目录，找到 download_files 相关的 yaml 配置文件（通常在 /models 下）。
打开配置文件，将 uri 中的 huggingface.co 替换为 hf-mirror.com。
例如：
uri: https://hf-mirror.com/TheBloke/Luna-AI-Llama2-Uncensored-GGUF/resolve/main/luna-ai-llama2-uncensored.Q4_0.gguf
部分旧版配置可能使用非 HTTPS 链接。请确保 URI 以 https:// 开头，并指向正确的 resolve 路径而非 main 分支路径。
访问 http://<服务器 IP>:16080 即可进入 LocalAI 的 Web UI。
除了 Curl，推荐使用 Python 进行业务集成。以下是一个简单的调用示例：
import requests
url = "http://localhost:16080/v1/chat/completions"
headers = {"Content-Type": "application/json"}
data = {
"model": "luna-ai-llama2",
"messages": [
{"role": "user", "content": "请简述人工智能的发展历史。"}
],
"temperature": 0.7
}
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
result = response.json()
print(result['choices'][0]['message']['content'])
else:
print(f"Error: {response.status_code}")
--models-path 挂载路径是否正确。LocalAI 为私有化部署大模型提供了一个轻量级且高效的解决方案。通过 Docker 容器化，开发者可以快速搭建推理服务，并利用 OpenAI 兼容的 API 无缝对接现有应用。尽管在国内网络环境下需要配置镜像源，但其灵活性和易用性使其成为企业级 LLM 落地的优选方案之一。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online