RamaLama — 在容器中运行本地 AI 模型的极简方案

RamaLama 致力于通过使用 OCI 容器，让 AI 工作变得简单、直观且熟悉。

项目描述

RamaLama 是一个开源工具，它通过熟悉的容器方法，简化了从任何来源本地使用和提供 AI 模型进行推理的过程。它允许工程师将容器中心的开发模式和优势扩展到 AI 用例中。

RamaLama 无需配置主机系统，而是拉取一个针对主机系统检测到的 GPU 定制的容器镜像，并允许您使用各种模型和平台。

• 消除了用户为 AI 配置主机系统的复杂性。
• 检测并拉取一个针对主机系统 GPU 定制的加速容器镜像，处理依赖项和硬件优化。
• RamaLama 支持多个 AI 模型仓库，包括 OCI 容器仓库。
• 模型的处理方式类似于 Podman 和 Docker 处理容器镜像。
• 使用常见的容器命令来处理 AI 模型。
• 在无根容器中安全地运行 AI 模型，将模型与底层主机隔离。
• 默认无网络访问，并在应用退出时删除所有临时数据，从而确保数据安全。
• 通过 REST API 或作为聊天机器人来与模型交互。
  
  

安装

在 macOS 上安装（独立安装包）

下载包含 Python 和所有依赖项的独立 macOS 安装包：

1. 从 Releases 下载最新的 .pkg 安装包
2. 双击安装，或运行：sudo installer -pkg RamaLama-*-macOS-Installer.pkg -target /

详细说明请参阅 macOS 安装指南。

在 Fedora 上安装

RamaLama 已在 Fedora 及更高版本中提供。要安装它，请运行：

sudo dnf install ramalama

通过 PyPI 安装

RamaLama 可通过 PyPI 获取：https://pypi.org/project/ramalama

pip install ramalama

安装脚本（Linux 和 macOS）

运行以下命令安装 RamaLama：

curl -fsSL https://ramalama.ai/install.sh | bash

在 Windows 上安装

RamaLama 支持带有 Docker Desktop 或 Podman Desktop 的 Windows：

pip install ramalama

要求：
- Python 3.10 或更高版本
- 带有 WSL2 后端的 Docker Desktop 或 Podman Desktop
- 对于 GPU 支持，请参阅 WSL2 的 NVIDIA GPU 设置

注意： Windows 支持需要通过 Docker/Podman 运行容器。模型存储使用硬链接（无需管理员权限），如果硬链接不可用，则回退到文件复制。

卸载

通过 pip 卸载

如果您使用 pip 安装了 RamaLama，可以使用以下命令卸载：

pip uninstall ramalama

在 Fedora 上卸载

如果您使用 DNF 安装了 RamaLama：

sudo dnf remove ramalama

在 macOS 上卸载（独立安装包）

要移除通过 .pkg 安装包安装的 RamaLama：

# 移除可执行文件
sudo rm /usr/local/bin/ramalama

# 移除配置和数据文件
sudo rm -rf /usr/local/share/ramalama

# 移除手册页（可选）
sudo rm /usr/local/share/man/man1/ramalama*.1
sudo rm /usr/local/share/man/man5/ramalama*.5
sudo rm /usr/local/share/man/man7/ramalama*.7

# 移除 shell 自动补全（可选）
sudo rm /usr/local/share/bash-completion/completions/ramalama
sudo rm /usr/local/share/fish/vendor_completions.d/ramalama.fish
sudo rm /usr/local/share/zsh/site-functions/_ramalama

更多详情请参阅 macOS 安装指南。

移除用户数据和配置

使用上述任何方法卸载 RamaLama 后，您可能希望移除下载的模型和配置文件：

# 移除下载的模型和数据（可能很大）
rm -rf -- "${XDG_DATA_HOME:-~/.local/share}/ramalama"

# 移除配置文件
rm -rf -- "${XDG_CONFIG_HOME:-~/.config}/ramalama"

# 如果您以 root 身份运行过 RamaLama，也请移除：
sudo rm -rf /var/lib/ramalama

注意： 模型数据目录（默认为 ~/.local/share/ramalama）可能非常大，具体取决于您下载了多少模型。在运行上述命令之前，请确保您确实要删除这些文件。

加速镜像

GPU 支持检测

首次运行时，RamaLama 会检测您系统的 GPU 支持情况，如果不存在则回退到 CPU。RamaLama 使用 Podman 或 Docker 等容器引擎拉取适当的 OCI 镜像，该镜像包含为您的系统设置运行 AI 模型所需的所有软件。

硬件支持

Nvidia GPU

在配备 NVIDIA GPU 的系统上，请参阅 ramalama-cuda 文档以了解正确的主机系统配置。

Intel GPU

以下 Intel GPU 可由 RamaLama 自动检测：

更多信息请参阅 Intel 硬件表。

Moore Threads GPU

在配备 Moore Threads GPU 的系统上，请参阅 ramalama-musa 文档以了解正确的主机系统配置。

MLX Runtime（仅限 macOS）

MLX 运行时为 Apple Silicon Mac 提供了优化的推理。MLX 要求：
- macOS 操作系统
- Apple Silicon 硬件（M1、M2、M3 或更高版本）
- 与 --nocontainer 选项一起使用（不支持容器）
- 主机系统上已安装 mlx-lm uv 包作为 uv 工具

要使用 uv 安装并运行 Phi-4 on MLX。如果未安装 uv，可以使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装：

uv tool install mlx-lm
# 或升级到最新版本：
uv tool upgrade mlx-lm

ramalama --runtime=mlx serve hf://mlx-community/Unsloth-Phi-4-4bit

默认容器引擎

当 Podman 和 Docker 都已安装时，RamaLama 默认使用 Podman。环境变量 RAMALAMA_CONTAINER_ENGINE=docker 可以覆盖此行为。当两者都未安装时，RamaLama 将尝试使用本地系统上的软件运行模型。

安全性

更安全地测试和运行您的模型

由于 RamaLama 默认使用 Podman 或 Docker 在无根容器内运行 AI 模型，这些容器将 AI 模型与底层主机的信息隔离开来。在 RamaLama 容器中，AI 模型以只读模式作为卷挂载到容器中。

这使得运行模型（llama.cpp 或 vLLM）的进程与主机隔离。此外，由于 ramalama run 使用 --network=none 选项，容器无法访问网络，从而防止信息从系统中泄露。最后，容器使用 --rm 选项运行，这意味着应用退出时，容器执行期间写入的任何内容都会被删除。

RamaLama 如何提供强大的安全特性：

• 容器隔离 – AI 模型在隔离的容器内运行，防止直接访问主机系统。
• 只读卷挂载 – AI 模型以只读模式挂载，这意味着容器内的进程无法修改主机文件。
• 无网络访问 – ramalama run 使用 --network=none 执行，意味着模型没有出站连接，信息无法泄露。
• 自动清理 – 容器使用 --rm 运行，会话结束后会清除所有临时数据。
• 丢弃所有 Linux 能力 – 无法访问 Linux 能力来攻击底层主机。
• 无新权限 – Linux 内核特性，禁止容器进程获取额外权限。
  
  

传输协议

RamaLama 支持多种称为传输协议的 AI 模型仓库类型。

支持的传输协议

默认传输协议

RamaLama 默认使用 Ollama 仓库传输协议

ramalama pull huggingface://afrideva/Tiny-Vicuna-1B-GGUF/tiny-vicuna-1b.q2_k.gguf

传输协议短名称

为了方便用户，RamaLama 使用短名称文件，其中包含完全指定的 AI 模型的别名，允许用户使用较短的名称来引用模型。

$ cat /usr/share/ramalama/shortnames.conf
[shortnames]
  "tiny" = "ollama://tinyllama"
  "granite" = "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf"
  "granite:7b" = "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf"
  "ibm/granite" = "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf"
  "merlinite" = "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf"
  "merlinite:7b" = "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf"
  ...

命令

[ramalama-bench](https://github.com/containers/ramalama/blob/main/docs/ramalama-bench.