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

Fedora Silverblue 和 Toolbox

在 Fedora Silverblue 和其他不可变发行版上，系统是只读的。您可以通过以下两种方式运行 RamaLama：

• Toolbox：创建一个 Toolbox 容器，并在其内安装 RamaLama（pip install ramalama 或 dnf install ramalama，如果可用）。使用宿主机上的 Podman（或 Docker），以便 RamaLama 能够启动模型容器；确保容器引擎已安装，并且 toolbox 能够访问宿主机的容器引擎（例如，通过绑定挂载套接字，或配置 toolbox 使用宿主机的 podman 命令）。
• 宿主机安装或具有宿主机访问权限的 Toolbox：如果您的镜像支持该软件包，可通过 rpm-ostree install ramalama 在宿主机上安装 RamaLama；或者在 toolbox 中运行 RamaLama，确保 Podman/Docker 可用，并且模型存储位于可写位置（例如，您的主目录）。

模型存储默认位于 ~/.local/share/ramalama，在 Silverblue 上是可写的。

通过 PyPI 安装

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

pip install ramalama

安装脚本（Linux 和 macOS）

通过运行以下命令安装 RamaLama：

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

在 Windows 上安装

RamaLama 支持 Windows 平台，需配合 Docker Desktop 或 Podman Desktop 使用：

pip install ramalama

要求：

• Python 3.10 或更高版本
• Docker Desktop 或 Podman Desktop，且后端为 WSL2
• 如需 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`）可能会非常大，具体取决于您下载了多少模型。在执行上述命令之前，请确保您确实希望删除这些文件。

## 加速镜像

| 加速器                       | 镜像                      |
| :---------------------------------| :------------------------- |
|  GGML_VK_VISIBLE_DEVICES (或 CPU) | quay.io/ramalama/ramalama  |
|  HIP_VISIBLE_DEVICES              | quay.io/ramalama/rocm      |
|  CUDA_VISIBLE_DEVICES             | quay.io/ramalama/cuda      |
|  ASAHI_VISIBLE_DEVICES            | quay.io/ramalama/asahi     |
|  INTEL_VISIBLE_DEVICES            | quay.io/ramalama/intel-gpu |
|  ASCEND_VISIBLE_DEVICES           | quay.io/ramalama/cann      |
|  MUSA_VISIBLE_DEVICES             | quay.io/ramalama/musa      |

### GPU 支持检测
首次运行时，RamaLama 会检查您的系统是否支持 GPU；如果未检测到 GPU，则会回退到 CPU。RamaLama 使用 Podman 或 Docker 等容器引擎来拉取适合您系统配置的 OCI 镜像，其中包含运行 AI 模型所需的所有软件。

<details>
<summary>
RamaLama 如何选择合适的镜像？
</summary>
<br>

初始化完成后，RamaLama 会在基于 OCI 镜像的容器内运行 AI 模型。RamaLama 会根据您系统中检测到的 GPU 拉取特定的容器镜像，这些镜像与 RamaLama 的次版本号绑定。
- 例如，在 NVIDIA 系统上运行 RamaLama 1.2.3 时，会拉取 quay.io/ramalama/cuda:1.2。若要覆盖默认镜像，可以使用 `--image` 选项。

随后，RamaLama 会从模型仓库中拉取 AI 模型，并通过一条简单的命令启动聊天机器人或 REST API 服务。模型的处理方式与 Podman 和 Docker 处理容器镜像的方式类似。
</details>
<br>

## 硬件支持

| 硬件                           | 已启用                     |
| :--------------------------------- | :-------------------------: |
| CPU                                | &check;                     |
| Apple Silicon GPU（Linux / Asahi）  | &check;                     |
| Apple Silicon GPU（macOS）          | &check; llama.cpp 或 MLX    |
| Apple Silicon GPU（podman-machine） | &check;                     |
| Nvidia GPU（cuda）                  | &check; 请参阅下方说明      |
| AMD GPU（rocm、vulkan）             | &check;                     |
| Ascend NPU（Linux）                 | &check;                     |
| Intel ARC GPUs（Linux）             | &check; 请参阅下方说明      |
| Intel GPUs（vulkan / Linux）        | &check;                     |
| Moore Threads GPU（musa / Linux）   | &check; 请参阅下方说明      |
| Windows（配合 Docker/Podman）       | &check; 需要 WSL2       |

### Nvidia GPUs
在配备 NVIDIA GPU 的系统上，请参阅 [ramalama-cuda](docs/ramalama-cuda.7.md) 文档，了解正确的主机系统配置。

### Intel GPUs
以下 Intel GPU 将由 RamaLama 自动检测：

| GPU ID  | 描述                        |
| :------ | :--------------------------------- |
|`0xe20b` | Intel® Arc™ B580 Graphics          |
|`0xe20c` | Intel® Arc™ B570 Graphics          |
|`0x7d51` | Intel® Graphics - Arrow Lake-H     |
|`0x7dd5` | Intel® Graphics - Meteor Lake      |
|`0x7d55` | Intel® Arc™ Graphics - Meteor Lake |

更多信息请参阅 [Intel 硬件表](https://dgpu-docs.intel.com/devices/hardware-table.html)。
<br>
<br>

### Moore Threads GPUs
在配备 Moore Threads GPU 的系统上，请参阅 [ramalama-musa](docs/ramalama-musa.7.md) 文档，了解正确的主机系统配置。

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

要在 MLX 上安装并运行 Phi-4，请使用 `uv`。如果尚未安装 `uv`，可以通过以下命令进行安装：`curl -LsSf https://astral.sh/uv/install.sh | sh`：
```bash
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

对指定的 AI 模型进行基准测试。

• 对指定的 AI 模型进行基准测试

  
  

  $ ramalama bench granite3-moe
  

ramalama-containers

列出所有 RamaLama 容器。

• 列出所有正在运行 AI 模型的容器

  
  

  $ ramalama containers
  

  返回示例：

  CONTAINER ID  IMAGE                             COMMAND               CREATED        STATUS                    PORTS                   NAMES
  85ad75ecf866  quay.io/ramalama/ramalama:latest  /usr/bin/ramalama...  5 小时前    Up 5 小时                0.0.0.0:8080->8080/tcp  ramalama_s3Oh6oDfOP
  85ad75ecf866  quay.io/ramalama/ramalama:latest  /usr/bin/ramalama...  4 分钟前  已退出 (0) 4 分钟前                          granite-server
  

• 以特定格式列出所有容器

  
  

  $ ramalama ps --noheading --format "{{ .Names }}"
  

  返回示例：

  ramalama_s3Oh6oDfOP
  granite-server
  

  </details。

ramalama-convert

将 AI 模型从本地存储转换为 OCI 镜像。

• 从 Ollama 模型生成 OCI 模型。

  
  

  $ ramalama convert ollama://tinyllama:latest oci://quay.io/rhatdan/tiny:latest
  

  返回示例：

  正在构建 quay.io/rhatdan/tiny:latest...
  第 1 步/共 2 步：FROM scratch
  第 2 步/共 2 步：复制 sha256:2af3b81862c6be03c769683af18efdadb2c33f60ff32ab6f83e42c043d6c7816 /model
  --> 使用缓存 69db4a10191c976d2c3c24da972a2a909adec45135a69dbb9daeaaf2a3a36344
  提交 quay.io/rhatdan/tiny:latest
  --> 69db4a10191c
  成功标记 quay.io/rhatdan/tiny:latest
  69db4a10191c976d2c3c24da972a2a909adec45135a69dbb9daeaaf2a3a36344
  

  </details。

• 生成并运行一个由 Safetensors 转换而来的量化 GGUF 的 OCI 模型。

  
  

  生成 OCI 模型

  $ ramalama --image quay.io/ramalama/ramalama-rag convert --gguf Q4_K_M hf://ibm-granite/granite-3.2-2b-instruct oci://quay.io/kugupta/granite-3.2-q4-k-m:latest
  

  返回示例：

  正在将 /Users/kugupta/.local/share/ramalama/models/huggingface/ibm-granite/granite-3.2-2b-instruct 转换为 quay.io/kugupta/granite-3.2-q4-k-m:latest...
  正在构建 quay.io/kugupta/granite-3.2-q4-k-m:latest...
  

  运行生成的模型

  $ ramalama run oci://quay.io/kugupta/granite-3.2-q4-k-m:latest
  

  </details。

ramalama-info

显示 RamaLama 的配置信息。

• 不使用容器引擎时的信息。

  
  

    $ ramalama info
    ```
    返回示例如下：
    ```
    {
        "Accelerator": "cuda",
        "Engine": {
        "Name": ""
        },
        "Image": "quay.io/ramalama/cuda:0.7",
        "Inference": {
            "Default": "llama.cpp",
            "Engines": {
                "llama.cpp": "/usr/share/ramalama/inference-spec/engines/llama.cpp.yaml",
                "mlx": "/usr/share/ramalama/inference-spec/engines/mlx.yaml",
                "vllm": "/usr/share/ramalama/inference-spec/engines/vllm.yaml"
            },
            "Schema": {
                "1-0-0": "/usr/share/ramalama/inference-spec/schema/schema.1-0-0.json"
            }
        },
        "Shortnames": {
        "Names": {
            "cerebrum": "huggingface://froggeric/Cerebrum-1.0-7b-GGUF/Cerebrum-1.0-7b-Q4_KS.gguf",
            "deepseek": "ollama://deepseek-r1",
            "dragon": "huggingface://llmware/dragon-mistral-7b-v0/dragon-mistral-7b-q4_k_m.gguf",
            "gemma3": "hf://bartowski/google_gemma-3-4b-it-GGUF/google_gemma-3-4b-it-IQ2_M.gguf",
            "gemma3:12b": "hf://bartowski/google_gemma-3-12b-it-GGUF/google_gemma-3-12b-it-IQ2_M.gguf",
            "gemma3:1b": "hf://bartowski/google_gemma-3-1b-it-GGUF/google_gemma-3-1b-it-IQ2_M.gguf",
            "gemma3:27b": "hf://bartowski/google_gemma-3-27b-it-GGUF/google_gemma-3-27b-it-IQ2_M.gguf",
            "gemma3:4b": "hf://bartowski/google_gemma-3-4b-it-GGUF/google_gemma-3-4b-it-IQ2_M.gguf",
            "granite": "ollama://granite3.1-dense",
            "granite-code": "hf://ibm-granite/granite-3b-code-base-2k-GGUF/granite-3b-code-base.Q4_K_M.gguf",
            "granite-code:20b": "hf://ibm-granite/granite-20b-code-base-8k-GGUF/granite-20b-code-base.Q4_K_M.gguf",
            "granite-code:34b": "hf://ibm-granite/granite-34b-code-base-8k-GGUF/granite-34b-code-base.Q4_K_M.gguf",
            "granite-code:3b": "hf://ibm-granite/granite-3b-code-base-2k-GGUF/granite-3b-code-base.Q4_K_M.gguf",
            "granite-code:8b": "hf://ibm-granite/granite-8b-code-base-4k-GGUF/granite-8b-code-base.Q4_K_M.gguf",
            "granite-lab-7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "granite-lab-8b": "huggingface://ibm-granite/granite-8b-code-base-GGUF/granite-8b-code-base.Q4_K_M.gguf",
            "granite-lab:7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "granite:2b": "ollama://granite3.1-dense:2b",
            "granite:7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "granite:8b": "ollama://granite3.1-dense:8b",
            "hermes": "huggingface://NousResearch/Hermes-2-Pro-Mistral-7B-GGUF/Hermes-2-Pro-Mistral-7B.Q4_K_M.gguf",
            "ibm/granite": "ollama://granite3.1-dense:8b",
            "ibm/granite:2b": "ollama://granite3.1-dense:2b",
            "ibm/granite:7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "ibm/granite:8b": "ollama://granite3.1-dense:8b",
            "merlinite": "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf",
            "merlinite-lab-7b": "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf",
            "merlinite-lab:7b": "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",
            "mistral": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
            "mistral:7b": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
            "mistral:7b-v1": "huggingface://TheBloke/Mistral-7B-Instruct-v0.1-GGUF/mistral-7b-instruct-v0.1.Q5_K_M.gguf",
            "mistral:7b-v2": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
            "mistral:7b-v3": "huggingface://MaziyarPanahi/Mistral-7B-Instruct-v0.3-GGUF/Mistral-7B-Instruct-v0.3.Q4_K_M.gguf",
            "mistral_code_16k": "huggingface://TheBloke/Mistral-7B-Code-16K-qlora-GGUF/mistral-7b-code-16k-qlora.Q4_K_M.gguf",
            "mistral_codealpaca": "huggingface://TheBloke/Mistral-7B-codealpaca-lora-GGUF/mistral-7b-codealpaca-lora.Q4_K_M.gguf",
            "mixtao": "huggingface://MaziyarPanahi/MixTAO-7Bx2-MoE-Instruct-v7.0-GGUF/MixTAO-7Bx2-MoE-Instruct-v7.0.Q4_K_M.gguf",
            "openchat": "huggingface://TheBloke/openchat-3.5-0106-GGUF/openchat-3.5-0106.Q4_K_M.gguf",
            "openorca": "huggingface://TheBloke/Mistral-7B-OpenOrca-GGUF/mistral-7b-openorca.Q4_K_M.gguf",
            "phi2": "huggingface://MaziyarPanahi/phi-2-GGUF/phi-2.Q4_K_M.gguf",
            "smollm:135m": "ollama://smollm:135m",
            "tiny": "ollama://tinyllama"
        },
        "Files": [
            "/usr/share/ramalama/shortnames.conf",
            "/home/dwalsh/.config/ramalama/shortnames.conf",
        ]
        },
        "Store": "/usr/share/ramalama",
        "UseContainer": true,
        "Version": "0.7.5"
    }
    ```
</details>

- <details>
    <summary>
        使用 Podman 引擎的信息。
    </summary>
    <br>

$ ramalama info
```
返回示例如下：
```
{
    "Accelerator": "cuda",
    "Engine": {
    "Info": {
        "host": {
        "arch": "amd64",
        "buildahVersion": "1.39.4",
        "cgroupControllers": [
            "cpu",
            "io",
            "memory",
            "pids"
        ],
        "cgroupManager": "systemd",
        "cgroupVersion": "v2",
        "conmon": {
            "package": "conmon-2.1.13-1.fc42.x86_64",
            "path": "/usr/bin/conmon",
            "version": "conmon version 2.1.13, commit: "
        },
        "cpuUtilization": {
            "idlePercent": 97.36,
            "systemPercent": 0.64,
            "userPercent": 2
        },
        "cpus": 32,
        "databaseBackend": "sqlite",
        "distribution": {
            "distribution": "fedora",
            "variant": "workstation",
            "version": "42"
        },
        "eventLogger": "journald",
        "freeLocks": 2043,
        "hostname": "danslaptop",
        "idMappings": {
            "gidmap": [
            {
                "container_id": 0,
                "host_id": 3267,
                "size": 1
            },
            {
                "container_id": 1,
                "host_id": 524288,
                "size": 65536
            }
            ],
            "uidmap": [
            {
                "container_id": 0,
                "host_id": 3267,
                "size": 1
            },
            {
                "container_id": 1,
                "host_id": 524288,
                "size": 65536
            }
            ]
        },
        "kernel": "6.14.2-300.fc42.x86_64",
        "linkmode": "dynamic",
        "logDriver": "journald",
        "memFree": 65281908736,
        "memTotal": 134690979840,
        "networkBackend": "netavark",
        "networkBackendInfo": {
            "backend": "netavark",
            "dns": {
            "package": "aardvark-dns-1.14.0-1.fc42.x86_64",
            "path": "/usr/libexec/podman/aardvark-dns",
            "version": "aardvark-dns 1.14.0"
            },
            "package": "netavark-1.14.1-1.fc42.x86_64",
            "path": "/usr/libexec/podman/netavark",
            "version": "netavark 1.14.1"
        },
        "ociRuntime": {
            "name": "crun",
            "package": "crun-1.21-1.fc42.x86_64",
            "path": "/usr/bin/crun",
            "version": "crun version 1.21\ncommit: 10269840aa07fb7e6b7e1acff6198692d8ff5c88\nrundir: /run/user/3267/crun\nspec: 1.0.0\n+SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +LIBKRUN +WASM:wasmedge +YAJL"
        },
        "os": "linux",
        "pasta": {
            "executable": "/bin/pasta",
            "package": "passt-0^20250415.g2340bbf-1.fc42.x86_64",
            "version": ""
        },
        "remoteSocket": {
            "exists": true,
            "path": "/run/user/3267/podman/podman.sock"
        },
        "rootlessNetworkCmd": "pasta",
        "security": {
            "apparmorEnabled": false,
            "capabilities": "CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_FOWNER,CAP_FSETID,CAP_KILL,CAP_NET_BIND_SERVICE,CAP_SETFCAP,CAP_SETGID,CAP_SETPCAP,CAP_SETUID,CAP_SYS_CHROOT",
            "rootless": true,
            "seccompEnabled": true,
            "seccompProfilePath": "/usr/share/containers/seccomp.json",
            "selinuxEnabled": true
        },
        "serviceIsRemote": false,
        "slirp4netns": {
            "executable": "/bin/slirp4netns",
            "package": "slirp4netns-1.3.1-2.fc42.x86_64",
            "version": "slirp4netns version 1.3.1\ncommit: e5e368c4f5db6ae75c2fce786e31eef9da6bf236\nlibslirp: 4.8.0\nSLIRP_CONFIG_VERSION_MAX: 5\nlibseccomp: 2.5.5"
        },
        "swapFree": 8589930496,
        "swapTotal": 8589930496,
        "uptime": "116h 35m 40.00s (Approximately 4.83 days)",
        "variant": ""
        },
        "plugins": {
        "authorization": null,
        "log": [
            "k8s-file",
            "none",
            "passthrough",
            "journald"
        ],
        "network": [
            "bridge",
            "macvlan",
            "ipvlan"
        ],
        "volume": [
            "local"
        ]
        },
        "registries": {
        "search": [
            "registry.fedoraproject.org",
            "registry.access.redhat.com",
            "docker.io"
        ]
        },
        "store": {
        "configFile": "/home/dwalsh/.config/containers/storage.conf",
        "containerStore": {
            "number": 5,
            "paused": 0,
            "running": 0,
            "stopped": 5
        },
        "graphDriverName": "overlay",
        "graphOptions": {},
        "graphRoot": "/usr/share/containers/storage",
        "graphRootAllocated": 2046687182848,
        "graphRootUsed": 399990419456,
        "graphStatus": {
            "Backing Filesystem": "btrfs",
            "Native Overlay Diff": "true",
            "Supports d_type": "true",
            "Supports shifting": "false",
            "Supports volatile": "true",
            "Using metacopy": "false"
        },
        "imageCopyTmpDir": "/var/tmp",
        "imageStore": {
            "number": 297
        },
        "runRoot": "/run/user/3267/containers",
        "transientStore": false,
        "volumePath": "/usr/share/containers/storage/volumes"
        },
        "version": {
        "APIVersion": "5.4.2",
        "BuildOrigin": "Fedora Project",
        "Built": 1743552000,
        "BuiltTime": "Tue Apr  1 19:00:00 2025",
        "GitCommit": "be85287fcf4590961614ee37be65eeb315e5d9ff",
        "GoVersion": "go1.24.1",
        "Os": "linux",
        "OsArch": "linux/amd64",
        "Version": "5.4.2"
        }
    },
    "Name": "podman"
    },
    "Image": "quay.io/ramalama/cuda:0.7",
    "Inference": {
        "Default": "llama.cpp",
        "Engines": {
            "llama.cpp": "/usr/share/ramalama/inference-spec/engines/llama.cpp.yaml",
            "mlx": "/usr/share/ramalama/inference-spec/engines/mlx.yaml",
            "vllm": "/usr/share/ramalama/inference-spec/engines/vllm.yaml"
        },
        "Schema": {
            "1-0-0": "/usr/share/ramalama/inference-spec/schema/schema.1-0-0.json"
        }
    },
    "Shortnames": {
        "Names": {
            "cerebrum": "huggingface://froggeric/Cerebrum-1.0-7b-GGUF/Cerebrum-1.0-7b-Q4_KS.gguf",
            "deepseek": "ollama://deepseek-r1",
            "dragon": "huggingface://llmware/dragon-mistral-7b-v0/dragon-mistral-7b-q4_k_m.gguf",
            "gemma3": "hf://bartowski/google_gemma-3-4b-it-GGUF/google_gemma-3-4b-it-IQ2_M.gguf",
            "gemma3:12b": "hf://bartowski/google_gemma-3-12b-it-GGUF/google_gemma-3-12b-it-IQ2_M.gguf",
            "gemma3:1b": "hf://bartowski/google_gemma-3-1b-it-GGUF/google_gemma-3-1b-it-IQ2_M.gguf",
            "gemma3:27b": "hf://bartowski/google_gemma-3-27b-it-GGUF/google_gemma-3-27b-it-IQ2_M.gguf",
            "gemma3:4b": "hf://bartowski/google_gemma-3-4b-it-GGUF/google_gemma-3-4b-it-IQ2_M.gguf",
            "granite": "ollama://granite3.1-dense",
            "granite-code": "hf://ibm-granite/granite-3b-code-base-2k-GGUF/granite-3b-code-base.Q4_K_M.gguf",
            "granite-code:20b": "hf://ibm-granite/granite-20b-code-base-8k-GGUF/granite-20b-code-base.Q4_K_M.gguf",
            "granite-code:34b": "hf://ibm-granite/granite-34b-code-base-8k-GGUF/granite-34b-code-base.Q4_K_M.gguf",
            "granite-code:3b": "hf://ibm-granite/granite-3b-code-base-2k-GGUF/granite-3b-code-base.Q4_K_M.gguf",
            "granite-code:8b": "hf://ibm-granite/granite-8b-code-base-4k-GGUF/granite-8b-code-base.Q4_K_M.gguf",
            "granite-lab-7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "granite-lab-8b": "huggingface://ibm-granite/granite-8b-code-base-GGUF/granite-8b-code-base.Q4_K_M.gguf",
            "granite-lab:7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "granite:2b": "ollama://granite3.1-dense:2b",
            "granite:7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "granite:8b": "ollama://granite3.1-dense:8b",
            "hermes": "huggingface://NousResearch/Hermes-2-Pro-Mistral-7B-GGUF/Hermes-2-Pro-Mistral-7B.Q4_K_M.gguf",
            "ibm/granite": "ollama://granite3.1-dense:8b",
            "ibm/granite:2b": "ollama://granite3.1-dense:2b",
            "ibm/granite:7b": "huggingface://instructlab/granite-7b-lab-GGUF/granite-7b-lab-Q4_K_M.gguf",
            "ibm/granite:8b": "ollama://granite3.1-dense:8b",
            "merlinite": "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf",
            "merlinite-lab-7b": "huggingface://instructlab/merlinite-7b-lab-GGUF/merlinite-7b-lab-Q4_K_M.gguf",
            "merlinite-lab:7b": "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",
            "mistral": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
            "mistral:7b": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
            "mistral:7b-v1": "huggingface://TheBloke/Mistral-7B-Instruct-v0.1-GGUF/mistral-7b-instruct-v0.1.Q5_K_M.gguf",
            "mistral:7b-v2": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf",
            "mistral:7b-v3": "huggingface://MaziyarPanahi/Mistral-7B-Instruct-v0.3-GGUF/Mistral-7B-Instruct-v0.3.Q4_K_M.gguf",
            "mistral_code_16k": "huggingface://TheBloke/Mistral-7B-Code-16K-qlora-GGUF/mistral-7b-code-16k-qlora.Q4_K_M.gguf",
            "mistral_codealpaca": "huggingface://TheBloke/Mistral-7B-codealpaca-lora-GGUF/mistral-7b-codealpaca-lora.Q4_K_M.gguf",
            "mixtao": "huggingface://MaziyarPanahi/MixTAO-7Bx2-MoE-Instruct-v7.0-GGUF/MixTAO-7Bx2-MoE-Instruct-v7.0.Q4_K_M.gguf",
            "openchat": "huggingface://TheBloke/openchat-3.5-0106-GGUF/openchat-3.5-0106.Q4_K_M.gguf",
            "openorca": "huggingface://TheBloke/Mistral-7B-OpenOrca-GGUF/mistral-7b-openorca.Q4_K_M.gguf",
            "phi2": "huggingface://MaziyarPanahi/phi-2-GGUF/phi-2.Q4_K_M.gguf",
            "smollm:135m": "ollama://smollm:135m",
            "tiny": "ollama://tinyllama"
        },
        "Files": [
            "/usr/share/ramalama/shortnames.conf",
            "/home/dwalsh/.config/ramalama/shortnames.conf",
        ]
    },
    "Store": "/usr/share/ramalama",
    "UseContainer": true,
    "Version": "0.7.5"
}
```

• 使用 jq 打印特定的 `ramalama info` 内容。

  
  

  $ ramalama info |  jq .Shortnames.Names.mixtao
  

  返回示例：

   "huggingface://MaziyarPanahi/MixTAO-7Bx2-MoE-Instruct-v7.0-GGUF/MixTAO-7Bx2-MoE-Instruct-v7.0.Q4_K_M.gguf"
  

ramalama-inspect

检查指定的人工智能模型。

• 检查 smollm:135m 模型的基本信息。

  
  

  $ ramalama inspect smollm:135m
  

  返回示例：

  smollm:135m
     路径：/var/lib/ramalama/models/ollama/smollm:135m
     注册表：ollama
     格式：GGUF
     版本：3
     字节序：小端
     元数据：39 条
     张量：272 条
  

• 以 JSON 格式检查 smollm:135m 模型的所有信息。

  
  

  $ ramalama inspect smollm:135m --all --json
  

  返回示例：

  {
      "Name": "smollm:135m",
      "Path": "/home/mengel/.local/share/ramalama/models/ollama/smollm:135m",
      "Registry": "ollama",
      "Format": "GGUF",
      "Version": 3,
      "LittleEndian": true,
      "Metadata": {
      "general.architecture": "llama",
      "general.base_model.0.name": "SmolLM 135M",
      "general.base_model.0.organization": "HuggingFaceTB",
      "general.base_model.0.repo_url": "https://huggingface.co/HuggingFaceTB/SmolLM-135M",
      ...
      },
      "Tensors": [
      {
          "dimensions": [
          576,
          49152
          ],
          "n_dimensions": 2,
          "name": "token_embd.weight",
          "offset": 0,
          "type": 8
      },
      ...
      ]
  }
  

ramalama-list

列出所有已下载的人工智能模型。

• 可以列出所有拉取到本地存储的模型。

  
  

  $ ramalama list
  

  返回示例：

  NAME                                                                    MODIFIED      SIZE
  ollama://smollm:135m                                                    16 hours ago  5.5M
  huggingface://afrideva/Tiny-Vicuna-1B-GGUF/tiny-vicuna-1b.q2_k.gguf     14 hours ago  460M
  ollama://moondream:latest                                               6 days ago    791M
  ollama://phi4:latest                                                    6 days ago    8.43 GB
  ollama://tinyllama:latest                                               1 week ago    608.16 MB
  ollama://granite3-moe:3b                                                1 week ago    1.92 GB
  ollama://granite3-moe:latest                                            3 months ago  1.92 GB
  ollama://llama3.1:8b                                                    2 months ago  4.34 GB
  ollama://llama3.1:latest                                                2 months ago  4.34 GB
  

ramalama-login

登录远程注册表。

• 登录 quay.io/username OCI 注册表

  
  

  $ export RAMALAMA_TRANSPORT=quay.io/username
  $ ramalama login -u username
  

• 登录 Ollama 注册表

  
  

  $ export RAMALAMA_TRANSPORT=ollama
  $ ramalama login
  

• 登录 Hugging Face 注册表

  
  

  $ export RAMALAMA_TRANSPORT=huggingface
  $ ramalama login --token=XYZ
  

  登录 Hugging Face 需要使用 hf 工具。有关安装和使用说明，请参阅 Hugging Face 命令行界面 的文档。

ramalama-logout

从远程注册表登出。

• 从 quay.io/username OCI 仓库登出

  
  

  $ ramalama logout quay.io/username
  

• 从 Ollama 注册表登出

  
  

  $ ramalama logout ollama
  

• 从 Hugging Face 登出

  
  

  $ ramalama logout huggingface
  

ramalama-perplexity

计算指定人工智能模型的困惑度。

• 计算人工智能模型的困惑度。

  
  困惑度用于衡量模型预测下一个标记的能力，数值越低表示性能越好。

  $ ramalama perplexity granite3-moe
  

ramalama-pull

从模型注册表将人工智能模型拉取到本地存储。

• 拉取一个模型

  
  可以使用 pull 命令拉取模型。默认情况下，它会从 Ollama 注册表 拉取。

  $ ramalama pull granite3-moe
  

ramalama-push

将人工智能模型从本地存储推送到远程注册表。

• 推送指定的人工智能模型（目前仅支持 OCI）

  
  模型可以来自 RamaLama 模型存储中的 Huggingface、Ollama 或 OCI 模型格式。该模型也可以只是存储在磁盘上的模型。

  $ ramalama push oci://quay.io/rhatdan/tiny:latest
  

ramalama-rag

从提供的文档中生成并转换检索增强生成（RAG）数据，将其打包成 OCI 镜像。

[!注意] 此命令需要容器引擎才能运行。

• 从提供的文档中生成 RAG 数据，并将其转换为 OCI 镜像。

  
  

  该命令使用包含 docling 工具的特定容器镜像，将指定内容转换为 RAG 向量数据库。如果本地不存在该镜像，RamaLama 将会拉取镜像并启动容器来处理数据。

  位置参数：

  PATH 包含 PDF、DOCX、PPTX、XLSX、HTML、AsciiDoc 和 Markdown 格式文件的文件或目录，可多次指定。

  IMAGE 用于存放处理后的 RAG 数据的 OCI 镜像名称

  ramalama rag ./README.md https://github.com/containers/podman/blob/main/README.md quay.io/ramalama/myrag
  100% |███████████████████████████████████████████████████████|  114.00 KB/    0.00 B 922.89 KB/s   59m 59s
  Building quay.io/ramalama/myrag...
  adding vectordb...
  c857ebc65c641084b34e39b740fdb6a2d9d2d97be320e6aa9439ed0ab8780fe0
  

  之后可以使用该镜像：

  ramalama run --rag quay.io/ramalama/myrag instructlab/merlinite-7b-lab
  

ramalama-rm

从本地存储中移除 AI 模型。

• 指定一个或多个要从本地存储中移除的 AI 模型。

  
  

  $ ramalama rm ollama://tinyllama
  

• 移除本地存储中的所有 AI 模型。

  
  

  $ ramalama rm --all
  

ramalama-run

将指定的 AI 模型作为聊天机器人运行。

• 使用 run 命令在模型上运行聊天机器人。默认情况下，它会从 Ollama 注册表 中拉取镜像。

  
  

  注意：RamaLama 会检查您的机器是否支持原生 GPU，然后使用 Podman 等容器引擎拉取包含适当代码和库的 OCI 容器镜像来运行 AI 模型。这可能需要较长时间进行设置，但仅在首次运行时发生。

  $ ramalama run instructlab/merlinite-7b-lab
  

• 在初始容器镜像下载完成后，您可以使用该容器镜像与不同的模型进行交互。

  
  

  $ ramalama run granite3-moe
  

  例如返回：

  > 写一个 Python 的 Hello World 程序
  
  print("Hello World")
  

• 在另一个终端窗口中查看正在运行的 Podman 容器。

  
  

  $ podman ps
  CONTAINER ID  IMAGE                             COMMAND               CREATED        STATUS        PORTS       NAMES
  91df4a39a360  quay.io/ramalama/ramalama:latest  /home/dwalsh/rama...  4 minutes ago  Up 4 minutes              gifted_volhard
  

ramalama-serve

在指定的 AI 模型上提供 REST API 服务。

• 提供模型服务并通过浏览器连接。

  
  

  $ ramalama serve llama3
  

  当启用 Web UI 时，您可以通过浏览器访问：127.0.0.1:<端口>。默认的服务端口为 8080（如果可用），否则会在 8081–8090 范围内随机选择一个空闲端口。如果您愿意，可以使用 --port/-p 参数指定要使用的端口。

• 同时运行两个 AI 模型。请注意，这两个模型都在 Podman 容器中运行。

  
  

  $ ramalama serve -d -p 8080 --name mymodel ollama://smollm:135m
  09b0e0d26ed28a8418fb5cd0da641376a08c435063317e89cf8f5336baf35cfa
  
  $ ramalama serve -d -n example --port 8081 oci://quay.io/mmortari/gguf-py-example/v1/example.gguf
  3f64927f11a5da5ded7048b226fbe1362ee399021f5e8058c73949a677b6ac9c
  
  $ podman ps
  CONTAINER ID  IMAGE                             COMMAND               CREATED         STATUS         PORTS                   NAMES
  09b0e0d26ed2  quay.io/ramalama/ramalama:latest  /usr/bin/ramalama...  32 seconds ago  Up 32 seconds  0.0.0.0:8081->8081/tcp  ramalama_sTLNkijNNP
  3f64927f11a5  quay.io/ramalama/ramalama:latest  /usr/bin/ramalama...  17 seconds ago  Up 17 seconds  0.0.0.0:8082->8082/tcp  ramalama_YMPQvJxN97
  

• 若要禁用 Web UI，请使用 `--webui` off 标志。

  
  

  $ ramalama serve --webui off llama3
  

ramalama-stop

停止正在运行 AI 模型的命名容器。

• 如果模型正在容器中运行，则停止该模型。

  
  

  $ ramalama stop mymodel
  

• 停止所有正在容器中运行的模型。

  
  

  $ ramalama stop --all
  

ramalama-version

显示 RamaLama 的版本。

• 打印 RamaLama 的版本。

  
  

  $ ramalama version
  

  例如返回：

  ramalama version 1.2.3
  

附录

图表

+---------------------------+
|                           |
| ramalama run granite3-moe |
|                           |
+-------+-------------------+
    |
    |
    |           +------------------+           +------------------+
    |           | 拉取推理       |           | 拉取模型层       |
    +-----------| 运行时 (cuda)   |---------->| granite3-moe     |
                +------------------+           +------------------+
                           | 仓库选项：    |
                           +-+-------+------+-+
                             |       |      |
                             v       v      v
                         +---------+ +------+ +----------+
                         | Hugging | | OCI  | | Ollama   |
                         | Face    | |      | | Registry |
                         +-------+-+ +---+--+ +-+--------+
                             |       |      |
                             v       v      v
                           +------------------+
                           | 使用       |
                           | cuda 运行时     |
                           | 和             |
                           | granite3-moe     |
                           +------------------+

开发中

关于这个 Alpha 版本，所有功能仍在开发中，因此可能会有不兼容的更改。如果您需要重置安装，请参阅上方的“卸载”部分，了解如何移除 RamaLama 并清理所有数据文件，然后重新安装。

已知问题

• 在 macOS 的某些 Python 版本上，证书可能未正确安装，从而导致 SSL 错误（例如，在访问 huggingface.co 时）。要解决这个问题，请运行“Install Certificates”命令，通常如下所示：

/Applications/Python 3.x/Install Certificates.command

感谢支持

没有以下项目的帮助，本项目将无法实现：

• llama.cpp
• vllm
• mlx-lm
• podman
• huggingface

所以，如果您喜欢这个工具，请给这些仓库点个赞，顺便也给我们点个赞吧。

社区

如需一般性问题或讨论，请使用 RamaLama 的

Matrix

对于问题/错误及功能相关的讨论，您可以使用 GitHub 的 Issues 和 PRs 跟踪系统。

社区/开发者聚会

我们每隔一周在 Discord 上举办一次面向公众的社区和开发者聚会，讨论项目发展方向，并为用户提供一个开放的交流平台，以便获得帮助、提问以及展示新功能。

加入 Discord 会议议程

路线图

查看完整的路线图。

贡献者

欢迎贡献者

RamaLama 快速上手指南

RamaLama 是一款开源工具，旨在通过 OCI 容器技术简化 AI 模型的本地运行与服务部署。它自动检测主机硬件（如 GPU），拉取对应的加速容器镜像，让开发者无需配置复杂的环境依赖即可运行各类大模型。

环境准备

系统要求

• 操作系统：Linux (推荐 Fedora/Ubuntu), macOS, Windows (需 WSL2)
• Python 版本：3.10 或更高
• 容器引擎（二选一）：
  • Podman（默认推荐，支持无根运行）
  • Docker
• Windows 用户额外要求：
  • 安装 Docker Desktop 或 Podman Desktop
  • 启用 WSL2 后端

硬件支持

RamaLama 会自动检测以下硬件并拉取对应优化的镜像：

• CPU: 通用支持
• NVIDIA GPU: 自动识别 CUDA 环境
• AMD GPU: 支持 ROCm 和 Vulkan
• Apple Silicon: 支持 macOS (MLX/llama.cpp) 及 Linux Asahi
• 其他: 支持 Intel ARC, 华为 Ascend (CANN), 摩尔线程 (MUSA) 等

安装步骤

根据您的需求选择一种安装方式：

方式一：一键脚本安装（推荐 Linux/macOS）

最简便的安装方式，自动处理依赖：

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

方式二：通过 PyPI 安装

如果您已配置好 Python 环境：

pip install ramalama

方式三：Fedora 系统安装

sudo dnf install ramalama

方式四：macOS 安装包

1. 从 Releases 页面 下载最新的 .pkg 文件。
2. 双击安装或运行命令：

sudo installer -pkg RamaLama-*-macOS-Installer.pkg -target /

方式五：Windows 安装

确保已安装 Docker/Podman 和 WSL2 后，在 PowerShell 中运行：

pip install ramalama

提示：若需加速下载，可配置国内 PyPI 镜像源：pip install ramalama -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

RamaLama 的使用逻辑类似于 docker run，但针对 AI 模型进行了优化。

1. 运行交互式聊天 (Run)

直接运行一个模型并进行对话。RamaLama 会自动下载模型并启动容器。 以下示例运行 Meta 的 Llama 3 模型（8B 参数量化版）：

ramalama run hf://meta-llama/Llama-3.2-3B-Instruct

注：首次运行会自动拉取模型和对应的容器镜像，请稍作等待。

2. 启动 API 服务 (Serve)

将模型作为 REST API 服务运行，供其他应用调用：

ramalama serve hf://meta-llama/Llama-3.2-3B-Instruct

服务默认监听在 http://localhost:8080。

3. 指定运行时或硬件

虽然 RamaLama 通常能自动检测硬件，您也可以手动指定：

• 强制使用 CPU 运行：

  ramalama run --runtime=llama.cpp hf://meta-llama/Llama-3.2-3B-Instruct
  

• macOS 上使用 MLX 加速（需先安装 mlx-lm）：

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

• 切换容器引擎（默认为 Podman，若需使用 Docker）：

  RAMALAMA_CONTAINER_ENGINE=docker ramalama run hf://meta-llama/Llama-3.2-3B-Instruct
  

4. 清理数据

卸载工具后，若需删除下载的模型和配置文件以释放空间：

# 删除模型数据 (可能占用较大空间)
rm -rf ~/.local/share/ramalama

# 删除配置文件
rm -rf ~/.config/ramalama