LocalAI 多模型服务¶

为什么要学 LocalAI¶

LocalAI 是一个兼容 OpenAI API 的本地推理服务，支持 LLM、图像生成、语音转文字、文字转语音等多种模型类型。与 Ollama 专注于 LLM 不同，LocalAI 提供了一个统一的 API 端点来管理和服务多种 AI 模型。对于需要在私有环境中搭建完整 AI 基础设施的团队来说，LocalAI 可以替代多个云 API 服务，实现数据不出内网的全栈 AI 能力。

核心概念¶

概念	白话解释	用途
Model Gallery	预配置的模型商店	一键下载各类预配置模型
Backend	底层推理引擎（llama.cpp/whisper等）	不同模型类型使用不同后端
YAML Config	每个模型的配置文件	定义模型参数、提示模板等
P2P Federation	节点间模型共享	多机协作分担负载
OpenAI 兼容	完全兼容 OpenAI API 格式	无缝替换云 API
GPU Splitting	模型跨 GPU 分片	大模型多卡并行

安装配置¶

Docker 部署（推荐）¶

# 基础版（仅 CPU）
docker run -p 8080:8080 --name local-ai \
  -v $PWD/models:/models \
  localai/localai:latest-cpu

# GPU 版本（NVIDIA）
docker run -p 8080:8080 --gpus all --name local-ai \
  -v $PWD/models:/models \
  localai/localai:latest-gpu-nvidia-cuda-12

# Docker Compose
cat > docker-compose.yml << 'EOF'
version: '3'
services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
      - ./config:/config
    environment:
      - MODELS_PATH=/models
      - CONFIG_PATH=/config
      - THREADS=8
      - CONTEXT_SIZE=4096
      - GALLERIES=[{"name":"model-gallery","url":"github:go-skynet/model-gallery/index.yaml"}]
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
EOF

docker compose up -d

二进制安装¶

# Linux
curl -Lo local-ai https://github.com/mudler/LocalAI/releases/latest/download/local-ai-linux-amd64
chmod +x local-ai
./local-ai --models-path ./models --threads 8

验证安装¶

curl http://localhost:8080/v1/models
# 应返回已加载模型列表

快速上手¶

从 Gallery 安装模型¶

# 列出可用模型
curl http://localhost:8080/models/available

# 安装模型
curl http://localhost:8080/models/apply -d '{
  "id": "huggingface@thebloke__llama-2-7b-chat-gguf__llama-2-7b-chat.Q5_K_M.gguf"
}'

# 或通过 Gallery 名称
curl http://localhost:8080/models/apply -d '{
  "id": "model-gallery@llama3-8b-instruct"
}'

手动配置模型¶

# config/llama3.yaml
name: llama3
backend: llama-cpp
parameters:
  model: llama-3-8b-instruct.Q5_K_M.gguf
  temperature: 0.7
  top_p: 0.9
  top_k: 40
  context_size: 8192
  threads: 8
  gpu_layers: 35

template:
  chat_message: |
    <|start_header_id|>{{.RoleName}}<|end_header_id|>
    {{.Content}}<|eot_id|>
  chat: |
    {{.Input}}
    <|start_header_id|>assistant<|end_header_id|>

stopwords:
  - "<|eot_id|>"
  - "<|end_header_id|>"

API 调用¶

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="none")

# Chat Completion
response = client.chat.completions.create(
    model="llama3",
    messages=[
        {"role": "system", "content": "你是有帮助的助手"},
        {"role": "user", "content": "什么是容器化？"}
    ],
    temperature=0.7,
)
print(response.choices[0].message.content)

# Embeddings
emb = client.embeddings.create(
    model="text-embedding-ada-002",
    input="Hello world"
)
print(len(emb.data[0].embedding))

进阶用法¶

多模型配置¶

# config/whisper.yaml
name: whisper-1
backend: whisper
parameters:
  model: ggml-whisper-large-v3.bin
  language: zh

# config/stablediffusion.yaml
name: dall-e
backend: stablediffusion
parameters:
  model: dreamshaper_8.safetensors
  scheduler: euler_a
  cfg_scale: 7

# config/tts.yaml
name: tts-1
backend: piper
parameters:
  model: zh_CN-huayan-medium.onnx

图像生成¶

curl http://localhost:8080/v1/images/generations -d '{
  "model": "dall-e",
  "prompt": "a cat sitting on a laptop, digital art",
  "size": "512x512"
}' -o response.json

语音转文字¶

curl http://localhost:8080/v1/audio/transcriptions \
  -F "model=whisper-1" \
  -F "file=@recording.mp3" \
  -F "language=zh"

负载均衡与高可用¶

# docker-compose-ha.yml
version: '3'
services:
  localai-1:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ['0']
              capabilities: [gpu]

  localai-2:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ['1']
              capabilities: [gpu]

  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

P2P 联邦模式¶

# 节点 1
local-ai --p2p --p2p-token "my-cluster-token" --models-path ./models

# 节点 2（自动发现节点 1 的模型）
local-ai --p2p --p2p-token "my-cluster-token" --models-path ./models

常见问题¶

Q: 与 Ollama 相比选择哪个？¶

Ollama：专注 LLM，体验更简洁，社区活跃
LocalAI：多模态统一 API，适合需要完整 AI 平台的场景

Q: 模型加载失败怎么排查？¶

# 查看日志
docker logs local-ai --tail 100

# 常见原因：
# 1. GGUF 文件损坏 → 重新下载
# 2. YAML 配置模板不匹配 → 检查 chat_message 模板
# 3. 显存不足 → 减少 gpu_layers 或降低 context_size

Q: 如何优化推理速度？¶

增加 threads 参数
合理设置 gpu_layers
使用 mmap: true 加速加载
减小 context_size 到实际需要的值

Q: 支持哪些模型格式？¶

GGUF（llama.cpp）、ONNX、SafeTensors（扩散模型）、whisper.cpp 格式、piper ONNX（TTS）等。

参考资源¶

GitHub：https://github.com/mudler/LocalAI
文档：https://localai.io/
Model Gallery：https://models.localai.io/
API 参考：https://localai.io/api-reference/
Discord：https://discord.gg/uJAeKSAGDy