Ollama Linux 部署与使用指南：命令、配置与排查

在 Linux 上使用 Ollama，可以按“启动服务 → 准备模型 → 验证推理 → 配置参数 → API 接入 → 排查资源与性能”的顺序操作。本文以带 systemd 的 Linux、本机访问为前提。所有命令都在 Bash 中执行；qwen3:8b 只是可替换的模型名称，/data/models/... 是需要替换的本地绝对路径。选择模型前，请确认磁盘、系统内存以及 GPU/显存是否能承载它。

先给出可直接操作的主流程，后面按需查 CLI、Modelfile、本地或微调模型导入、服务参数、多轮调用和性能定位。安装和 HTTP 示例需要 curl；Python 示例需要 Python 3 和 venv；解析性能响应的命令需要 jq。这些工具按所用发行版安装，不需要为了执行某一节而预先安装全部工具。

导入行为涉及版本差异；本文按 2026 年 10 月 25 日核对的官方文档和 v0.34.1 发布说明描述，操作时以本机的 ollama --version 和实际输出为准。

从安装到首次调用

官方给出了下面的安装方式。该命令会下载并执行官方安装脚本；在服务器上执行前，先确认来源与环境符合自己的运维要求。[9]

curl -fsSL https://ollama.com/install.sh | sh
ollama --version

# 带 systemd 的 Linux：启动服务并设置开机启动
sudo systemctl enable --now ollama
sudo systemctl status ollama

systemctl status 打开分页器时按 q 退出。若环境没有 systemd，可在一个终端运行 ollama serve，另开终端使用下面的 CLI 和 API 命令。已经由 systemd 管理服务时，无须再启动第二个 ollama serve。使用 NVIDIA GPU 可先运行 nvidia-smi 核对驱动识别状态。[9]

确认服务可用后，从模型库准备一个模型：

ollama pull qwen3:8b     # 下载到本机
ollama ls                # 看磁盘上已有的模型
ollama show qwen3:8b     # 看模型信息
ollama run qwen3:8b      # 进入交互聊天

进入 ollama run 后可提问，也可临时调整上下文：

/set parameter num_ctx 4096
请用中文解释 KV Cache。
/clear
/bye

/clear 清理这个交互会话的上下文；/bye 退出终端聊天。退出不等于从磁盘删除模型，也不保证它立即从运行内存卸载。固定默认设置的方法见 Modelfile 一节。[1][2]

单次提问和附带统计输出：

ollama run qwen3:8b "用中文解释 KV Cache。"
ollama run qwen3:8b "用中文解释 KV Cache。" --verbose

--verbose 可查看命令行返回的耗时和 token 统计；需要保存和分析各阶段指标时，使用后文的非流式 API。[1][18]

通过本地 HTTP 接口做一次非流式调用，能确认服务可供应用访问：[14]

curl -sS http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3:8b","messages":[{"role":"user","content":"你好"}],"think":false,"stream":false}'

返回 JSON 中的 message.content 是本轮回答；如果模型尚未加载，首次请求可能包含加载时间。后续再用 ollama ps 核对它加载在哪种处理器上。这里针对 Qwen3 设置 think: false，后文的普通聊天示例也采用这一设置；更换模型后需确认它支持的思考控制方式。[14][15]

常用 CLI 命令速查

ollama run 是客户端调用；ollama serve 是服务器进程。ls 和 ps 观察的是不同位置。命令帮助随版本可能变化，可执行 ollama --help 与 ollama run --help 核对本机用法。[1][2][10]

Modelfile：设置模型默认参数

Modelfile 至少需要一个 FROM。它可以引用已经下载的 Ollama 模型，也可以在受支持的情况下指向本地模型文件。PARAMETER 设置推理参数，SYSTEM 设置系统提示，TEMPLATE 决定消息最终怎样被组织成模型输入。创建新名称不是训练或微调权重。[10]

先从已经下载的模型创建一个带默认设置的版本：

cat > Modelfile <<'EOF'
FROM qwen3:8b

PARAMETER num_ctx 4096
PARAMETER num_predict 1024
PARAMETER temperature 0.7

SYSTEM 你是一名中文技术助手，请清楚、准确地回答问题。
EOF

ollama create my-assistant -f ./Modelfile
ollama show --modelfile my-assistant
ollama run my-assistant

上面的 4096、1024、0.7 是示例设置，需按模型与任务调整。官方页面对默认上下文的描述有差异，因此这里显式设定，并用 ollama ps 核对实际分配值。[2][10][11][14]

导入本地与微调后的模型

先识别文件与微调产物

“权重文件”“GGUF”“模型目录”不是同一层概念。权重是模型参数；格式说明如何保存它们；目录可以把权重、结构配置、分词器和生成配置放在一起。扩展名本身不说明是否经过微调，也不保证文件包含完整模型。[3][4]

一个 Hugging Face 风格的完整模型目录可能长这样，路径指向整个目录而非其中某一个分片：

my-finetuned-model/
├── config.json
├── model-00001-of-00002.safetensors
├── model-00002-of-00002.safetensors
├── model.safetensors.index.json
├── tokenizer.json
├── tokenizer_config.json
└── generation_config.json

这只是示意，实际文件名随模型和导出工具变化。config.json 描述结构；两个 model-* 是同一模型的权重分片，索引文件记录参数分布；tokenizer* 决定文本与 token ID 的转换。分成两个文件不等于需要两张 GPU。对话模型还要留意 chat template：消息如何被排成训练时使用的提示词格式。[3]

微调后的产物主要有三条分支：

1. 完整权重：保存了整个更新后模型；部署时不需要再加载一份独立适配器。
2. LoRA 等适配器：例如 adapter_config.json 与 adapter_model.safetensors，只保存相对于训练时基础模型的增量，运行时仍需要对应的基础模型。
3. 合并后的完整权重：在方法支持时，把适配器更新合并进基础模型，再导出完整模型。PEFT 的 merge_and_unload() 是一种合并接口，但不能假设所有 PEFT 方法和量化组合都能合并。[4]

训练检查点还可能保存优化器、学习率调度器和训练步数，以便恢复训练；推理部署通常不需要这些状态。判断产物时，先问“有没有完整权重？”，再问“当前格式和架构能否被 Ollama 使用？”，比只看一个后缀可靠。[4][5]

在这里，“转成 GGUF”与“量化”是两步：前者换保存格式，后者调整权重表示精度以降低体积和内存需求。一个 GGUF 文件也可以是高精度版本；Q4_K_M 是量化类型，不能把它等同于“GGUF 格式”。[6]

本地 GGUF：修改 FROM

手里已经有本地 GGUF 时，保存下面的内容为一个新的 Modelfile，主要变化是 FROM 指向文件绝对路径：

FROM /data/models/my-model-Q4_K_M.gguf
PARAMETER num_ctx 4096
PARAMETER num_predict 1024

然后执行：

ollama create my-local-model -f ./Modelfile
ollama show my-local-model
ollama run my-local-model

上面路径是示例，需要替换；Ollama 在导入时不会替 GGUF 做量化。如果是拆分的 GGUF，官方文档给出了保留原分片名并用通配符指向所有分片的写法。格式正确也仍需架构受支持。[6]

完整模型目录：转换与量化

如果只有微调后的 Hugging Face 完整权重目录，Linux 上可以先用适用该架构的 llama.cpp 工具转为 GGUF，再按需要量化，最后导入 Ollama。下面的命令在 llama.cpp 源码目录中执行，前提是已安装转换脚本依赖、编译出 llama-quantize，且转换器支持目标架构。[6][12]

python3 convert_hf_to_gguf.py /data/models/my-model-merged \
  --outfile /data/models/my-model-f16.gguf \
  --outtype f16

./build/bin/llama-quantize \
  /data/models/my-model-f16.gguf \
  /data/models/my-model-Q4_K_M.gguf \
  Q4_K_M

转换后的模型要核对 tokenizer、特殊 token 与 chat template，尤其是微调时改过这些内容的情况。可以先测高精度版本，再测量化版本，固定同一组问题比较格式、停止位置和回答质量。量化可能造成质量变化，成功加载不能代替任务测试。[3][12]

Safetensors 直接导入与 LoRA 的版本限制

官方导入页还给出了 Safetensors 模型目录的 FROM /path/to/directory 形式；但 v0.34.1 发布说明把 Safetensors ollama create 与 MLX 后端联系起来，并说明 GGUF 的转换、量化改由 llama.cpp 工具完成。因而在 Linux 上，不能只因为有 model.safetensors 就假定可直接创建；需要对照所装 Ollama 版本、模型架构和后端核实。[6][12]

在确认环境支持目录导入后，Modelfile 的形式是：

FROM /data/models/my-finetuned-model
PARAMETER num_ctx 4096
PARAMETER num_predict 1024

创建、查看和运行仍使用 ollama create、ollama show、ollama run；目录中应为完整模型，而不是只有 adapter_model.safetensors 的适配器目录。

旧文章中直接用 ADAPTER 挂载 LoRA 的方法在 v0.34.1 源码中会报“不再支持 LoRA adapters”。持有适配器时，先确认训练所用的基础模型与 tokenizer，再用训练框架在支持的条件下合并、导出完整权重，最后按前述步骤转换和导入。[4][13]

资源预算：权重、上下文与显存

先用一个粗略公式建立数量级：

权重理论体积 ≈ 参数量 × 每个参数的位数 ÷ 8
运行时内存需求 ≈ 权重 + KV Cache + 计算缓冲及其他开销

例如假设是 80 亿参数：16 bit 纯权重约 16 GB，8 bit 约 8 GB，4 bit 约 4 GB。这里按十进制单位估算，忽略量化元数据、混合精度、模型结构差异和运行开销，不能直接拿结果当最低显存要求。KV Cache 保存生成过程可复用的注意力信息；上下文越长、同时处理的请求越多，缓存预算越值得关注。[7][8]

实际选型需要同时看磁盘空间、GPU 与驱动、可用显存、系统内存以及期望的速度。Ollama 可以把模型加载到 GPU、CPU，或两者混合；即使模型能启动，部分权重卸载到 CPU 也可能明显改变响应速度。安装和首次运行后，用 ollama ps 查看 PROCESSOR 与 CONTEXT，比只看模型下载大小更有依据。100% GPU 表示模型全部加载在 GPU，不是 GPU 计算利用率持续 100%。[2][8]

服务参数：上下文、并发、队列和驻留

Modelfile 管某个模型的默认行为；HTTP 请求中的 options 可以为这次调用指定参数；systemd 环境变量影响 Ollama 服务。先知道各层的职责，避免在普通终端里 export 后，以为后台服务已经改变。[2][10]

对同一推理参数，请求中的显式 options 优先于模型默认值；模型未指定时再使用服务或运行时的默认设置。检查 OLLAMA_CONTEXT_LENGTH 时也要查看请求和 Modelfile 是否另设了 num_ctx。修改 OLLAMA_MODELS 只改变服务查找模型的位置，不能代替移动文件；新目录还需要对服务用户可读写。[2][10][14]

这些值会相互影响。官方的并发说明举例：2K 上下文、4 个并行请求会分配相当于 8K 的上下文空间；这不表示整个模型权重也需要复制四份。增大队列允许更多请求等待，不会提高 GPU 的处理能力。首次配置可先设单并发，测试稳定后再逐项增加。[2]

在 systemd 管理的 Linux 上执行：

sudo systemctl edit ollama

在打开的编辑器中写入，例如：

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=4096"
Environment="OLLAMA_NUM_PARALLEL=1"
Environment="OLLAMA_MAX_LOADED_MODELS=1"
Environment="OLLAMA_MAX_QUEUE=32"
Environment="OLLAMA_KEEP_ALIVE=10m"

保存并退出，然后运行：

sudo systemctl daemon-reload
sudo systemctl restart ollama
sudo systemctl show ollama -p Environment

这是起步配置示例，无须同时设置所有项。改动并发或上下文后要重新看 ollama ps、GPU 状态和请求延迟；“配置被 systemd 读取”与“推理时实际分配多少”应分别检查。[2]

默认本机监听为 127.0.0.1:11434。本地 API 默认无认证；只有明确需要跨机器访问时，才应调整 OLLAMA_HOST，并设计实际的访问控制，不能把开放监听当成访问控制。[2]

API：单次请求、流式输出与模型驻留

服务启动、模型准备好后，程序直接调用 HTTP API，不需要先打开 ollama run。原生 /api/chat 接收 messages；options 管本次推理；stream 决定返回方式；keep_alive 管本次请求后模型在内存中待多久。[14]

下面调用已经下载的 qwen3:8b，并一次返回完整 JSON：

curl -sS http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {"role": "user", "content": "解释模型量化为什么能节省显存。"}
    ],
    "think": false,
    "stream": false,
    "options": {
      "num_ctx": 4096,
      "num_predict": 512,
      "temperature": 0
    },
    "keep_alive": "10m"
  }'

模型可能另有思考输出能力。是否支持 think、有哪些取值，应通过所用模型的能力说明或 /api/show 核对；不要把某个模型的开关当成所有模型的通用行为。[15]

要边生成边显示，改用流式响应：

curl -N http://localhost:11434/api/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {"role": "user", "content": "解释什么是 KV Cache。"}
    ],
    "think": false,
    "stream": true
  }'

原生接口会返回逐行 JSON（NDJSON）。应用要逐行解析，拼接消息内容，并读到 done: true；一个网络片段不保证等于一个 token。耗时与 token 统计在最后的完成片段中。流式让用户更早看到内容，不保证整次生成更快。[14][16]

请求的 keep_alive 覆盖服务的默认驻留设置，但不是保留模型的绝对保证：服务停止和资源调度仍可能使模型卸载。它与 messages 代表的对话历史是两回事。要预加载模型，可以发一条空的生成请求：[2]

curl -sS http://localhost:11434/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3:8b","keep_alive":"10m"}'

多轮对话：由应用保留消息

磁盘、运行内存和应用历史分别保存什么

部署和聊天涉及三种不同的状态：磁盘上的模型文件、服务运行时加载的模型与缓存、应用保存的对话消息。它们的生命周期也不同。

ollama ls 查询磁盘模型，ollama ps 查询运行状态，应用中的 messages 则是本轮提交的对话。清空应用的消息数组不会删除磁盘模型；停止运行模型也不等于删除应用保存的聊天记录。[1][2][14]

Python 多轮聊天

第二轮问题如果依赖第一轮，就需要应用把相关消息再放进 messages。模型留在显存里，并不表示 /api/chat 替应用保存了完整会话。下面是一个可运行的最小 Python 示例，当前进程内存保存历史；程序退出后这份历史也随之消失。[14][17]

python3 -m venv .venv
source .venv/bin/activate
python -m pip install ollama

保存为 chat_demo.py：

from ollama import Client

client = Client(host="http://localhost:11434")
system_message = {
    "role": "system",
    "content": "你是一名中文技术助手，请清楚、准确地回答。"
}
messages = [system_message]

while True:
    question = input("你：").strip()

    if question == "/bye":
        break
    if question == "/clear":
        messages = [system_message]
        print("已清空当前会话历史")
        continue
    if not question:
        continue

    turn = {"role": "user", "content": question}
    response = client.chat(
        model="qwen3:8b",
        messages=messages + [turn],
        think=False,
        stream=False,
        options={"num_ctx": 4096, "num_predict": 512},
        keep_alive="10m",
    )
    answer = response.message.content
    messages.extend([turn, {"role": "assistant", "content": answer}])
    print("助手：", answer)

运行：

python chat_demo.py

程序会在每次请求前组装历史，并在请求成功后把本轮问题和实际回答加入 messages。/clear 清空当前程序中的历史，/bye 退出。实际应用还需要控制历史长度，为当前输入与输出留出上下文预算；截断、摘要或外部存储由应用设计。这个最小程序没有实现历史持久化、重试和长会话裁剪。[8][14]

性能定位：加载、输入处理、输出生成

一次非流式请求的响应里，Ollama 提供多个阶段指标，所有耗时字段的单位都是纳秒：[18]

平均生成速度可按 eval_count × 10⁹ ÷ eval_duration 算成 token/s。它只描述生成阶段，不包含加载、排队和输入处理。total_duration 也不必机械地等于三个阶段相加；客户端感受到的总耗时，还包含网络和客户端处理。非流式调用看不到首个输出到达的时刻；要测首 token 延迟，应以流式请求在客户端记录开始与首个有效输出片段的时间。对于有思考输出的模型，还应区分首个思考片段与首个最终回答片段。[16][18]

比较首次调用与后续调用

可用同一组输入比较模型卸载后的首次调用与后续调用。以下示例在 Bash 中执行，jq 用于读 JSON，--fail-with-body 需要 curl 7.76.0 或更新版本。把函数放进当前 shell：

request_model() {
  curl -sS --fail-with-body \
    http://localhost:11434/api/chat \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "qwen3:8b",
      "messages": [
        {"role": "user", "content": "用三句话解释模型量化。"}
      ],
      "think": false,
      "stream": false,
      "options": {"num_ctx": 4096, "num_predict": 256, "temperature": 0},
      "keep_alive": "10m"
    }' \
    -o "$1" \
    -w 'HTTP=%{http_code} 客户端耗时=%{time_total}s\n'
}

然后依次执行：

ollama stop qwen3:8b
request_model cold.json
request_model warm.json

jq -r '
  "total=\(.total_duration / 1e9)s " +
  "load=\(.load_duration / 1e9)s " +
  "input=\(.prompt_eval_count) " +
  "cached=\(.prompt_eval_cached_count // 0) " +
  "prefill=\(.prompt_eval_duration / 1e9)s " +
  "output=\(.eval_count) " +
  "decode=\(.eval_duration / 1e9)s " +
  "tokens/s=\(if .eval_duration > 0
               then .eval_count * 1e9 / .eval_duration
               else 0 end)"
' cold.json warm.json

这次测试针对 qwen3:8b 关闭思考输出，方便比较回答生成耗时；切换模型时需确认该控制是否受支持。若 HTTP 状态不是 200，先读响应文件中的错误信息，再计算指标。[14][15]

ollama stop 卸载运行中的模型，所以下次调用通常需要重新加载；这个动作不清空操作系统的文件缓存。两次输入相同还可能让后一次命中提示词缓存，比较时应同时看 load_duration 和 prompt_eval_cached_count，不能把耗时下降全部归因于“热加载”。缓存计数字段在旧版本可能缺失，示例中的 // 0 仅让显示兼容缺失值，不能据此证明没有缓存。[2][18]

比较不同并发配置

先保持 OLLAMA_NUM_PARALLEL=1，预热模型后运行下面的四请求批次，记录整体耗时、各请求耗时和 GPU 占用。随后只把 OLLAMA_NUM_PARALLEL 改成 2，重启、预热并运行同一批次。两轮保持 num_ctx、模型和输出上限相同：

time (
  for i in 1 2 3 4; do
    request_model "parallel-$i.json" &
  done
  wait
)

这只是教学用的小样本，并非正式压测。相同提示词可能命中缓存；更严谨的比较要固定模型、输入长度、输出上限和机器负载，并多次重复。并发提高时，单个请求的延迟也可能变长。[2][18]

流式测量首次输出时间

下面的程序复用前文安装的 Python SDK，通过 time.perf_counter() 记录客户端时间。保存为 stream_timing.py 后执行 python stream_timing.py：

from time import perf_counter
from ollama import Client

client = Client(host="http://localhost:11434")
started = perf_counter()
first_fragment = None
first_answer = None
final = None

stream = client.chat(
    model="qwen3:8b",
    messages=[{"role": "user", "content": "解释 KV Cache。"}],
    stream=True,
    options={"num_ctx": 4096, "num_predict": 512},
    keep_alive="10m",
)

for chunk in stream:
    now = perf_counter()
    thinking = chunk.message.thinking or ""
    content = chunk.message.content or ""
    if first_fragment is None and (thinking or content):
        first_fragment = now - started
    if first_answer is None and content:
        first_answer = now - started
    if content:
        print(content, end="", flush=True)
    if chunk.done:
        final = chunk

elapsed = perf_counter() - started
print()
print("首个非空输出片段（秒）：", first_fragment)
print("首个回答片段（秒）：", first_answer)
print("客户端总耗时（秒）：", elapsed)
if final is not None:
    print("生成 token 数：", final.eval_count)
    print("服务端总耗时（纳秒）：", final.total_duration)

这是应用侧首次接收输出的测量，包含排队、加载、输入处理和传输等影响。片段可能包含多个 token，因此与推理引擎内部的严格首 token 时间有差别。开启思考的模型可能先返回 thinking，稍后才返回 content，分别记录能解释“已经在生成，但界面还没有最终回答”的等待。[14][15][16][17]

故障排查与日常管理

根据现象查相应的命令与指标：

常用检查命令：

ollama ls                         # 磁盘上的模型
ollama ps                         # 当前加载的模型、处理器与上下文
ollama show --modelfile qwen3:8b  # 模型默认配置
nvidia-smi                        # NVIDIA GPU 状态
sudo journalctl -u ollama -f       # 服务日志，Ctrl+C 退出
ollama stop qwen3:8b               # 卸载运行模型，保留磁盘文件

只有确定不再需要本地模型文件时，才用 ollama rm 模型名 删除；停止整个服务用 sudo systemctl stop ollama。ls、ps、stop、rm 指向不同状态，不应互相替代。[1][2][9]

资料与版本边界

• [1] Ollama CLI Reference
• [2] Ollama FAQ：上下文、环境变量、模型驻留和并发
• [3] Transformers 模型加载、保存与分片
• [4] PEFT checkpoint 与适配器合并
• [5] PyTorch 保存与加载模型及训练检查点
• [6] Ollama 导入模型：Safetensors 与 GGUF
• [7] Transformers 量化概览
• [8] Transformers KV Cache 说明
• [9] Ollama Linux 安装与服务
• [10] Ollama Modelfile Reference
• [11] Ollama 上下文长度与 ollama ps
• [12] Ollama v0.34.1 发布说明；llama.cpp GGUF 量化工具
• [13] Ollama v0.34.1 源码中的适配器限制
• [14] Ollama Chat API
• [15] Ollama Thinking 能力与模型支持
• [16] Ollama Streaming
• [17] Ollama Python SDK
• [18] Ollama API 耗时与 token 指标

本文已核对公开接口与命令说明，未在目标 Linux GPU 环境中复现部署、导入或压测。实际 GPU 加载、生成速度和微调模型的回答质量需要在目标机器验证。