Gollama

Gollama 是一款用于管理 Ollama 模型的 macOS / Linux 工具。

它提供了一个文本用户界面（TUI），用于列出、检查、删除、复制和推送 Ollama 模型。

该应用程序允许用户通过热键交互式地选择模型、排序、过滤、编辑、运行、卸载以及对模型执行其他操作。

目录

• Gollama
  • 目录
  • 特性
  • 安装
  • 使用
  • 配置
  • 从源码安装与构建
  • 日志记录
  • 贡献
  • 致谢
  • 许可证

特性

Gollama 是一款具有易用界面的 Ollama 模型管理工具。

目前仍在积极开发中，因此可能存在一些 bug 和缺失的功能。不过，我每天都在使用它来管理我的模型，尤其是在清理旧模型时非常有用。

• 列出可用的模型
• 显示元数据，如大小、量化级别、模型家族和修改日期
• 编辑/更新模型的 Modelfile
• 按名称、大小、修改日期、量化级别、家族等对模型进行排序
• 选择并删除模型
• 运行和卸载模型
• 检查模型以获取更多详细信息
• 计算模型的大致 vRAM 使用量
• 复制/重命名模型
• 将模型推送到注册表
• 显示正在运行的模型
• 有一些有趣的 bug

另请参阅 - ingest，用于将代码目录/仓库转换为适合 LLM 的 Markdown 格式。

---

更新 [2025-12-02]：移除 LM Studio 链接功能及 Gollama 维护放缓

自 Gollama 的 v2.0.1 版本 发布以来，LM Studio 链接功能将不再可用。

与 LM Studio 之间的链接维护起来越来越麻烦，得不偿失。由于上游应用程序不断变化，同时还要适应每个用户的本地配置，这让我投入了过多的时间去维护一个我很少使用的功能。

我自己现在也不再频繁使用 Ollama 了。这也导致开发进度放缓，因为我把精力放在了其他项目上。

我曾是 Ollama 的早期采用者和贡献者，但到了 2025 年，我对 Ollama 的价值已经大不如前，几乎不再使用它。对于模型推理服务，我主要转向了使用 llama.cpp，并结合 llama-swap 来运行。过去一年里，llama.cpp 变得更加易用，项目维护良好，配置更简单，功能也多了很多，性能更是显著提升。而在笔记本电脑上运行模型时，我则使用 LM Studio，因为它既支持 MLX 模型，也支持标准的 llama.cpp 运行时来处理 GGUF 模型。

---

安装

go install（推荐）

go install github.com/sammcj/gollama/v2@latest

curl

我不建议使用这种方法，因为它不易于更新，但你也可以使用以下命令：

curl -sL https://raw.githubusercontent.com/sammcj/gollama/refs/heads/main/scripts/install.sh | bash

手动安装

从 发布页面 下载最新版本，然后将二进制文件解压到你的 PATH 中的一个目录。

例如：zip -d gollama*.zip -d gollama && mv gollama /usr/local/bin

如果出现“command not found: gollama”

如果看到此错误，请在 .zshrc 或 .bashrc 中添加环境变量。

echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc
source ~/.zshrc

使用

要运行 gollama 应用程序，可以使用以下命令：

gollama

提示：我喜欢将 gollama 设置为 g 的别名，以便快速访问：

echo "alias g=gollama" >> ~/.zshrc

快捷键

• Space: 选择
• Enter: 运行模型（Ollama run）
• i: 检查模型
• t: Top（显示正在运行的模型）
• D: 删除模型
• e: 编辑模型
• c: 复制模型
• U: 卸载所有模型
• p: 拉取现有模型
• ctrl+k: 拉取模型并保留用户配置
• ctrl+p: 拉取新模型
• P: 推送模型
• n: 按名称排序
• s: 按大小排序
• m: 按修改日期排序
• k: 按量化级别排序
• f: 按家族排序
• B: 按参数量排序
• r: 重命名模型 (正在进行中)
• q: 退出

Top

Top (t)

检查

Inspect (i)

命令行选项

模型管理：

• -l: 列出所有可用的 Ollama 模型并退出
• -s <search term>: 按名称搜索模型
  • OR 运算符（'term1|term2'）返回匹配任一术语的模型
  • AND 运算符（'term1&term2'）返回同时匹配两个术语的模型
• -e <model>: 编辑模型的 Modelfile
• -u: 卸载所有正在运行的模型
• -v: 打印版本号并退出

配置：

• -h 或 --host: 指定 Ollama API 的主机
• -H: -h http://localhost:11434 的快捷方式（连接到本地 Ollama API）
• --ollama-dir: 自定义 Ollama 模型目录
• --log 或 --log-level: 覆盖日志级别（debug、info、warn、error）

清理：

• --no-cleanup: 不清理损坏的符号链接

vRAM 分析：

• --vram: 估算模型的 vRAM 使用量。接受：
  • Ollama 模型（如 llama3.1:8b-instruct-q6_K、qwen2:14b-q4_0）
  • HuggingFace 模型（如 NousResearch/Hermes-2-Theta-Llama-3-8B）
  • --fits: 可用内存（GB）用于上下文计算（如 6 表示 6GB）
  • --vram-to-nth 或 --context: 最大上下文长度（如 32k 或 128k）
  • --quant: 覆盖量化级别（如 Q4_0、 Q5_K_M）

简单的模型列表

Gollama 也可以通过 -l 命令调用，以不使用 TUI 的方式列出模型。

gollama -l

列表（gollama -l）：

编辑

Gollama 可以通过 -e 命令调用，以编辑某个模型的 Modelfile。

gollama -e my-model

搜索

Gollama 可以通过 -s 命令调用，以按名称搜索模型。

gollama -s my-model # 返回包含 'my-model' 的模型

gollama -s 'my-model|my-other-model' # 返回包含 'my-model' 或 'my-other-model' 的模型

gollama -s 'my-model&instruct' # 返回同时包含 'my-model' 和 'instruct' 的模型

vRAM 估计

Gollama 包含全面的 vRAM 估计功能：

• 计算已拉取的 Ollama 模型（如 my-model:mytag）或 HuggingFace 模型 ID（如 author/name）的 vRAM 使用量
• 根据给定的 vRAM 限制确定最大上下文长度
• 在给定的 vRAM 和上下文限制下找到最佳量化设置
• 显示不同 k/v 缓存量化选项的估算值（fp16、q8_0、q4_0）
• 自动检测可用的 CUDA vRAM（即将推出！）或系统 RAM

要估算 vRAM 使用量：

gollama --vram llama3.1:8b-instruct-q6_K

📊 VRAM Estimation for Model: llama3.1:8b-instruct-q6_K

| 量化   | 上下文 | BPW | 2K  | 8K              | 16K             | 32K             | 49K             | 64K |
| ------- | ---- | --- | --- | --------------- | --------------- | --------------- | --------------- |
| IQ1_S   | 1.56 | 2.2 | 2.8 | 3.7(3.7,3.7)    | 5.5(5.5,5.5)    | 7.3(7.3,7.3)    | 9.1(9.1,9.1)    |
| IQ2_XXS | 2.06 | 2.6 | 3.3 | 4.3(4.3,4.3)    | 6.1(6.1,6.1)    | 7.9(7.9,7.9)    | 9.8(9.8,9.8)    |
| IQ2_XS  | 2.31 | 2.9 | 3.6 | 4.5(4.5,4.5)    | 6.4(6.4,6.4)    | 8.2(8.2,8.2)    | 10.1(10.1,10.1) |
| IQ2_S   | 2.50 | 3.1 | 3.8 | 4.7(4.7,4.7)    | 6.6(6.6,6.6)    | 8.5(8.5,8.5)    | 10.4(10.4,10.4) |
| IQ2_M   | 2.70 | 3.2 | 4.0 | 4.9(4.9,4.9)    | 6.8(6.8,6.8)    | 8.7(8.7,8.7)    | 10.6(10.6,10.6) |
| IQ3_XXS | 3.06 | 3.6 | 4.3 | 5.3(5.3,5.3)    | 7.2(7.2,7.2)    | 9.2(9.2,9.2)    | 11.1(11.1,11.1) |
| IQ3_XS  | 3.30 | 3.8 | 4.5 | 5.5(5.5,5.5)    | 7.5(7.5,7.5)    | 9.5(9.5,9.5)    | 11.4(11.4,11.4) |
| Q2_K    | 3.35 | 3.9 | 4.6 | 5.6(5.6,5.6)    | 7.6(7.6,7.6)    | 9.5(9.5,9.5)    | 11.5(11.5,11.5) |
| Q3_K_S  | 3.50 | 4.0 | 4.8 | 5.7(5.7,5.7)    | 7.7(7.7,7.7)    | 9.7(9.7,9.7)    | 11.7(11.7,11.7) |
| IQ3_S   | 3.50 | 4.0 | 4.8 | 5.7(5.7,5.7)    | 7.7(7.7,7.7)    | 9.7(9.7,9.7)    | 11.7(11.7,11.7) |
| IQ3_M   | 3.70 | 4.2 | 5.0 | 6.0(6.0,6.0)    | 8.0(8.0,8.0)    | 9.9(9.9,9.9)    | 12.0(12.0,12.0) |
| Q3_K_M  | 3.91 | 4.4 | 5.2 | 6.2(6.2,6.2)    | 8.2(8.2,8.2)    | 10.2(10.2,10.2) | 12.2(12.2,12.2) |
| IQ4_XS  | 4.25 | 4.7 | 5.5 | 6.5(6.5,6.5)    | 8.6(8.6,8.6)    | 10.6(10.6,10.6) | 12.7(12.7,12.7) |
| Q3_K_L  | 4.27 | 4.7 | 5.5 | 6.5(6.5,6.5)    | 8.6(8.6,8.6)    | 10.7(10.7,10.7) | 12.7(12.7,12.7) |
| IQ4_NL  | 4.50 | 5.0 | 5.7 | 6.8(6.8,6.8)    | 8.9(8.9,8.9)    | 10.9(10.9,10.9) | 13.0(13.0,13.0) |
| Q4_0    | 4.55 | 5.0 | 5.8 | 6.8(6.8,6.8)    | 8.9(8.9,8.9)    | 11.0(11.0,11.0) | 13.1(13.1,13.1) |
| Q4_K_S  | 4.58 | 5.0 | 5.8 | 6.9(6.9,6.9)    | 8.9(8.9,8.9)    | 11.0(11.0,11.0) | 13.1(13.1,13.1) |
| Q4_K_M  | 4.85 | 5.3 | 6.1 | 7.1(7.1,7.1)    | 9.2(9.2,9.2)    | 11.4(11.4,11.4) | 13.5(13.5,13.5) |
| Q4_K_L  | 4.90 | 5.3 | 6.1 | 7.2(7.2,7.2)    | 9.3(9.3,9.3)    | 11.4(11.4,11.4) | 13.6(13.6,13.6) |
| Q5_K_S  | 5.54 | 5.9 | 6.8 | 7.8(7.8,7.8)    | 10.0(10.0,10.0) | 12.2(12.2,12.2) | 14.4(14.4,14.4) |
| Q5_0    | 5.54 | 5.9 | 6.8 | 7.8(7.8,7.8)    | 10.0(10.0,10.0) | 12.2(12.2,12.2) | 14.4(14.4,14.4) |
| Q5_K_M  | 5.69 | 6.1 | 6.9 | 8.0(8.0,8.0)    | 10.2(10.2,10.2) | 12.4(12.4,12.4) | 14.6(14.6,14.6) |
| Q5_K_L  | 5.75 | 6.1 | 7.0 | 8.1(8.1,8.1)    | 10.3(10.3,10.3) | 12.5(12.5,12.5) | 14.7(14.7,14.7) |
| Q6_K    | 6.59 | 7.0 | 8.0 | 9.4(9.4,9.4)    | 12.2(12.2,12.2) | 15.0(15.0,15.0) | 17.8(17.8,17.8) |
| Q8_0    | 8.50 | 8.8 | 9.9 | 11.4(11.4,11.4) | 14.4(14.4,14.4) | 17.4(17.4,17.4) | 20.3(20.3,20.3) |

要为给定的内存限制（例如 6GB）找到最佳量化类型，可以使用 `--fits <GB 数>` 参数：

```shell
gollama --vram NousResearch/Hermes-2-Theta-Llama-3-8B --fits 6

📊 VRAM 预估：模型 - NousResearch/Hermes-2-Theta-Llama-3-8B

| 量化/上下文 | BPW  | 2K  | 8K  | 16K          | 32K           | 49K            | 64K             |
| --------- | ---- | --- | --- | ------------ | ------------- | -------------- | --------------- |
| IQ1_S     | 1.56 | 2.4 | 3.8 | 5.7(4.7,4.2) | 9.5(7.5,6.5)  | 13.3(10.3,8.8) | 17.1(13.1,11.1) |
| IQ2_XXS   | 2.06 | 2.9 | 4.3 | 6.3(5.3,4.8) | 10.1(8.1,7.1) | 13.9(10.9,9.4) | 17.8(13.8,11.8) |
...

这将显示一张表格，列出不同量化类型和上下文长度下的显存占用情况。

显存估算器的工作原理如下：

1. 从 Hugging Face 获取模型配置（如果本地未缓存）。
2. 计算模型参数、激活值和 KV 缓存所需的内存。
3. 根据指定的量化设置调整计算结果。
4. 使用二分搜索和线性搜索优化上下文长度或量化设置。

注意：估算器会优先使用 CUDA 显存，如果没有可用的 CUDA 显存，则会回退到系统内存进行计算。

配置

Gollama 使用位于 ~/.config/gollama/config.json 的 JSON 配置文件。该配置文件包含排序选项、列设置、API 密钥、日志级别、主题等配置项。

示例配置：

{
  "default_sort": "modified",
  "columns": [
    "Name",
    "Size",
    "Quant",
    "Family",
    "Modified",
    "ID"
  ],
  "ollama_api_key": "",
  "ollama_api_url": "http://localhost:11434",
  "log_level": "info",
  "log_file_path": "/Users/username/.config/gollama/gollama.log",
  "sort_order": "Size",
  "strip_string": "my-private-registry.internal/",
  "editor": "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code",
  "docker_container": ""
}

• strip_string 可用于移除模型名称前缀，以便在 TUI 中更清晰地显示。如果你的模型名称带有私有仓库等常见前缀，可以通过此设置将其移除。
• editor 指定了按下 'e' 键时使用的编辑器。如果为空，则会回退到 EDITOR 环境变量，最后默认使用 vim。支持外部编辑器（如 VS Code），并会弹出界面供用户编辑。
• docker_container - 实验性 - 如果设置，Gollama 将尝试在指定的容器内执行所有运行操作。
• theme - 实验性 主题名称（不带 .json 后缀）。

安装与源码构建

1. 克隆仓库：

   git clone https://github.com/sammcj/gollama.git
   cd gollama
   

2. 构建：

   go get
   make build
   

3. 运行：

   ./gollama
   

主题

Gollama 支持基本的自定义主题功能，主题以 JSON 文件形式存储在 ~/.config/gollama/themes/ 目录中。可通过配置文件中的 theme 设置来选择当前主题（不带 .json 后缀）。

如果默认主题不存在，系统会自动创建：

• default - 带霓虹色点缀的暗色主题（默认）
• light-neon - 带霓虹色点缀的浅色主题，适合浅色终端背景。

创建自定义主题的步骤如下：

1. 在 themes 目录中创建一个新的 JSON 文件（例如 ~/.config/gollama/themes/my-theme.json）。
2. 使用以下结构：

{
  "name": "my-theme",
  "description": "我的自定义主题",
  "colours": {
    "header_foreground": "#AA1493",
    "header_border": "#BA1B11",
    "selected": "#FFFFFF",
    ...
  },
  "family": {
    "llama": "#FF1493",
    "alpaca": "#FF00FF",
    ...
  }
}

颜色可以使用 ANSI 颜色代码（如 241）或十六进制值（如 #FF00FF）指定。family 部分用于定义列表视图中不同模型家族的颜色。

注意：使用 VSCode 扩展插件 'Color Highlight' 可以更方便地查找颜色的十六进制值。

日志

日志文件位于 gollama.log，默认存储在 $HOME/.config/gollama/gollama.log。

日志级别可以在配置文件中设置，也可以通过命令行覆盖：

# 覆盖单个命令的日志级别
gollama -C --log debug

# 或者使用长格式
gollama --create-from-lmstudio --log-level debug

可用的日志级别：debug、info、warn、error

贡献

欢迎贡献！ 请先 fork 仓库，然后创建包含您更改的 pull request。

Sam	Cameron Kingsbury	KimCookieYa	lif	Denis Balan	Doug Coleman
Impact	Jose Almaraz	Jose Roberto Almaraz	Oleksii Filonenko	SouthWolf	Vigilans
agustif	anrgct	ondrej

致谢

• Ollama
• Llama.cpp
• Charmbracelet

感谢 Matt Williams、Fahd Mirza 和 AI Code King 等人试用并提供了反馈。

许可证

版权所有 © 2024 Sam McLeod

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

Gollama 快速上手指南

Gollama 是一款专为 macOS 和 Linux 设计的终端用户界面（TUI）工具，用于高效管理 Ollama 模型。它支持模型的列表、检查、删除、复制、推送、运行及显存（vRAM）估算等功能。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统：macOS 或 Linux
• 前置依赖：
  • 已安装并运行 Ollama 服务。
  • 已安装 Go 语言环境（推荐版本 1.21+，用于通过 go install 安装）。
• 网络环境：确保能够访问 GitHub 及 Go 模块仓库（国内用户若遇网络问题，可配置 GOPROXY）。

安装步骤

推荐使用 go install 方式进行安装，便于后续更新。

方法一：使用 Go 安装（推荐）

在终端执行以下命令：

go install github.com/sammcj/gollama/v2@latest

注意：如果执行 gollama 提示 command not found，请将 Go 的二进制目录添加到环境变量中：

echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc
source ~/.zshrc

(注：如果你使用的是 bash，请将 .zshrc 替换为 .bashrc)

方法二：手动安装

1. 前往 Releases 页面 下载最新版本的压缩包。
2. 解压并将二进制文件移动到系统路径中：

unzip gollama*.zip
mv gollama /usr/local/bin

可选：设置别名

为了方便快速启动，建议设置简短别名（例如 g）：

echo "alias g=gollama" >> ~/.zshrc
source ~/.zshrc

基本使用

1. 启动交互式界面

直接在终端输入以下命令即可启动图形化终端界面：

gollama

常用快捷键操作：

按键	功能说明
Space	选中/取消选中模型
Enter	运行选中的模型 (ollama run)
i	检查模型详细信息 (Inspect)
t	查看正在运行的模型 (Top)
D	删除选中的模型
e	编辑模型的 Modelfile
c	复制/重命名模型
U	卸载所有已加载的模型
p	拉取现有模型
ctrl+p	拉取新模型
P	推送模型到注册表
n / s / m	分别按名称、大小、修改时间排序
q	退出程序

2. 命令行模式

如果不进入交互界面，也可以使用命令行参数直接操作：

列出所有模型：

gollama -l

搜索模型：

# 搜索包含 'llama3' 的模型
gollama -s llama3

# 逻辑或搜索 (包含 'llama3' 或 'instruct')
gollama -s 'llama3|instruct'

# 逻辑与搜索 (同时包含 'llama3' 和 'instruct')
gollama -s 'llama3&instruct'

编辑模型配置：

gollama -e my-model-name

卸载所有运行中的模型：

gollama -u

3. 显存 (vRAM) 估算

Gollama 提供强大的显存估算功能，可帮助判断模型在特定量化等级和上下文长度下的显存占用。

估算特定模型的显存占用：

gollama --vram llama3.1:8b-instruct-q6_K

根据可用显存查找合适的量化版本： 假设你只有 6GB 显存，想找出能运行的最佳量化版本：

gollama --vram NousResearch/Hermes-2-Theta-Llama-3-8B --fits 6

该命令会输出一个表格，展示不同量化等级（如 Q4_0, Q5_K_M 等）在不同上下文长度（2K, 8K, 16K...）下的显存需求，帮助你做出最佳选择。