本地部署 | 林子杨的个人网站

Ollama实用指南：本地部署与管理大型语言模型

Fri, 27 Jun 2025 02:00:00 +0000

1. 简介

Ollama 是一个强大的开源工具，旨在让用户能够轻松地在本地环境下载、运行和管理大型语言模型（LLM）。它的核心优势在于简化了部署和使用复杂模型的流程，使得开发者、研究人员和爱好者无需专业的硬件或复杂的配置，即可在个人计算机上体验和利用 state-of-the-art 的人工智能技术。

主要优势:

易于使用: 通过简单的命令行指令，即可完成模型的下载、运行和交互。
跨平台支持: 支持 macOS, Windows, 和 Linux。
模型库丰富: 支持众多流行的开源模型，如 Llama 3, Mistral, Gemma, Phi-3 等。
高度可定制: 通过 Modelfile，用户可以轻松地自定义模型的行为、系统提示和参数。
API 驱动: 提供 REST API，方便与其他应用程序和服务集成。
开源社区: 拥有活跃的社区，不断贡献新的模型和功能。

本篇文档将深入浅出地介绍 Ollama 的各项功能，从基础入门到高级应用，帮助您全面掌握这个强大的工具。

2. 快速入门

本节将指导您完成 Ollama 的安装和基本使用。

2.1 安装

访问 Ollama 官方网站下载适用于您操作系统的安装包并进行安装。

2.2 运行第一个模型

安装完成后，打开终端（或命令提示符），使用 ollama run 命令来下载并运行一个模型。例如，运行 Llama 3 模型：

ollama run llama3

首次运行时，Ollama 会自动从模型库下载所需的模型文件。下载完成后，您就可以直接在终端与模型进行对话。

2.3 管理本地模型

您可以使用以下命令来管理本地已下载的模型：

列出本地模型:
```
ollama list
```
该命令会显示所有已下载模型的名称、ID、大小和修改时间。
移除本地模型:
```
ollama rm <model_name>
```

3. 核心概念

3.1 Modelfile

Modelfile 是 Ollama 的核心功能之一，它是一个类似于 Dockerfile 的配置文件，允许您定义和创建自定义模型。通过 Modelfile，您可以：

指定基础模型。
设置模型参数（如温度、top_p 等）。
定义模型的系统提示（System Prompt）。
自定义模型的交互模板。
应用 LoRA 适配器。

一个简单的 Modelfile 示例：

# 指定基础模型
FROM llama3
# 设置模型温度
PARAMETER temperature 0.8
# 设置系统提示
SYSTEM """
You are a helpful AI assistant. Your name is Roo.
"""

使用 ollama create 命令基于 Modelfile 创建新模型：

ollama create my-custom-model -f ./Modelfile

3.2 模型导入

Ollama 支持从外部文件系统导入模型，特别是从 Safetensors 格式的权重文件。

在 Modelfile 中，使用 FROM 指令并提供包含 safetensors 文件的目录路径：

FROM /path/to/safetensors/directory

然后使用 ollama create 命令创建模型。

3.3 多模态模型

Ollama 支持多模态模型（如 LLaVA），可以同时处理文本和图像输入。

ollama run llava "这张图片里有什么? /path/to/image.png"

4. API 参考

Ollama 提供了一套 REST API，用于以编程方式与模型进行交互。默认服务地址为 http://localhost:11434。

4.1 `/api/generate`

生成文本。

请求 (Streaming):

curl http://localhost:11434/api/generate -d '{
"model": "llama3",
"prompt": "Why is the sky blue?"
}'

请求 (Non-streaming):

curl http://localhost:11434/api/generate -d '{
"model": "llama3",
"prompt": "Why is the sky blue?",
"stream": false
}'

4.2 `/api/chat`

进行多轮对话。

请求:

curl http://localhost:11434/api/chat -d '{
"model": "llama3",
"messages": [
{
"role": "user",
"content": "why is the sky blue?"
}
],
"stream": false
}'

4.3 `/api/embed`

生成文本的嵌入向量。

请求:

curl http://localhost:11434/api/embed -d '{
"model": "all-minilm",
"input": ["Why is the sky blue?", "Why is the grass green?"]
}'

4.4 `/api/tags`

列出本地所有可用的模型。

请求:
```
curl http://localhost:11434/api/tags
```

5. 命令行工具 (CLI)

Ollama 提供了一套丰富的命令行工具来管理模型和与服务交互。

ollama run <model>: 运行一个模型。
ollama create <model> -f <Modelfile>: 从 Modelfile 创建一个模型。
ollama pull <model>: 从远程库拉取一个模型。
ollama push <model>: 将一个模型推送到远程库。
ollama list: 列出本地模型。
ollama cp <source_model> <dest_model>: 复制一个模型。
ollama rm <model>: 删除一个模型。
ollama ps: 查看正在运行的模型及其资源占用。
ollama stop <model>: 停止一个正在运行的模型并将其从内存中卸载。

6. 高级功能

6.1 OpenAI API 兼容性

Ollama 提供了一个与 OpenAI API 兼容的端点，允许您将现有的 OpenAI 应用无缝迁移到 Ollama。默认地址为 http://localhost:11434/v1。

列出模型 (Python):

from openai import OpenAI
client = OpenAI(
base_url='http://localhost:11434/v1',
api_key='ollama', # required, but unused
)
response = client.models.list()
print(response)

6.2 结构化输出

结合使用 OpenAI 兼容 API 和 Pydantic，可以强制模型输出特定结构的 JSON。

from pydantic import BaseModel
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
class UserInfo(BaseModel):
name: str
age: int
try:
completion = client.beta.chat.completions.parse(
model="llama3.1:8b",
messages=[{"role": "user", "content": "My name is John and I am 30 years old."}],
response_format=UserInfo,
)
print(completion.choices[0].message.parsed)
except Exception as e:
print(f"Error: {e}")

6.3 性能调优

您可以通过环境变量来调整 Ollama 的性能和资源管理：

OLLAMA_KEEP_ALIVE: 设置模型在内存中保持活动状态的时间。例如 10m, 24h, 或 -1 (永久)。
OLLAMA_MAX_LOADED_MODELS: 同时加载到内存中的最大模型数量。
OLLAMA_NUM_PARALLEL: 每个模型可以并行处理的请求数量。

6.4 LoRA 适配器

在 Modelfile 中使用 ADAPTER 指令来应用一个 LoRA (Low-Rank Adaptation) 适配器，从而在不修改基础模型权重的情况下，改变模型的行为。

FROM llama3
ADAPTER /path/to/your-lora-adapter.safetensors

7. 附录

7.1 故障排除

检查 CPU 特性: 在 Linux 上，可以使用以下命令检查 CPU 是否支持 AVX 等指令集，这对于某些模型的性能至关重要。
```
cat /proc/cpuinfo | grep flags | head -1
```

7.2 贡献指南

Ollama 是一个开源项目，欢迎社区贡献。在提交代码时，请遵循良好的提交消息格式，例如：

Good: llm/backend/mlx: support the llama architecture
Bad: feat: add more emoji

7.3 相关链接

官方网站: https://ollama.com/
GitHub 仓库: https://github.com/ollama/ollama
模型库: https://ollama.com/library

Llama.cpp 技术详解：轻量级大模型推理引擎

Thu, 26 Jun 2025 01:06:00 +0000

1. 引言

Llama.cpp 是一个用 C/C++ 编写的高性能、轻量级的大型语言模型 (LLM) 推理框架。它专注于在消费级硬件上高效运行 LLM，实现了在普通笔记本电脑甚至手机上进行本地推理的可能。

核心优势:

高性能: 通过优化的 C/C++ 代码、量化技术和硬件加速支持（如 Apple Metal, CUDA, OpenCL, SYCL），实现了极快的推理速度。
轻量级: 极低的内存和计算资源消耗，无需昂贵的 GPU 即可运行。
跨平台: 支持 macOS, Linux, Windows, Docker, Android, 和 iOS 等多种平台。
开放生态: 拥有活跃的社区和丰富的生态系统，包括 Python 绑定、UI 工具和与 OpenAI 兼容的服务器。
持续创新: 快速跟进并实现最新的模型架构和推理优化技术。

2. 核心概念

2.1. GGUF 模型格式

GGUF (Georgi Gerganov Universal Format) 是 llama.cpp 使用的核心模型文件格式，是其前身 GGML 的演进版本。GGUF 是一个专为快速加载和内存映射设计的二进制格式。

主要特点:

统一文件: 将模型元数据、词汇表和所有张量（权重）打包在单个文件中。
可扩展性: 允许在不破坏兼容性的情况下添加新的元数据。
向后兼容: 保证了对旧版本 GGUF 模型的兼容。
内存效率: 支持内存映射（mmap），允许多个进程共享同一模型权重，从而节省内存。

2.2. 量化 (Quantization)

量化是 llama.cpp 的核心优势之一。它是一种将模型权重从高精度浮点数（如 32 位或 16 位）转换为低精度整数（如 4 位、5 位或 8 位）的技术。

主要优势:

减小模型体积: 显著降低模型文件的大小，使其更易于分发和存储。
降低内存占用: 减少了模型加载到内存中所需的 RAM。
加速推理: 低精度计算通常比高精度计算更快，尤其是在 CPU 上。

llama.cpp 支持多种量化方法，特别是 k-quants，这是一种先进的量化技术，能够在保持较高模型性能的同时实现极高的压缩率。

2.3. 多模态支持

llama.cpp 不仅仅局限于文本模型，它已经发展成为一个强大的多模态推理引擎，支持同时处理文本、图像甚至音频。

支持的模型: 支持如 LLaVA, MobileVLM, Granite, Qwen2.5 Omni, InternVL, SmolVLM 等多种主流多模态模型。
工作原理: 通常通过一个视觉编码器（如 CLIP）将图像转换为嵌入向量，然后将这些向量与文本嵌入向量一起输入到 LLM 中。
使用工具: llama-mtmd-cli 和 llama-server 提供了对多模态模型的原生支持。

3. 使用方法

3.1. 编译

从源码编译 llama.cpp 非常简单。

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
make

对于特定硬件加速（如 CUDA 或 Metal），需要使用相应的编译选项：

# For CUDA
make LLAMA_CUDA=1
# For Metal (on macOS)
make LLAMA_METAL=1

3.2. 基本推理

编译后，可以使用 llama-cli 工具进行推理。

./llama-cli -m ./models/7B/ggml-model-q4_0.gguf -p "Building a website can be done in 10 simple steps:" -n 400

-m: 指定 GGUF 模型文件的路径。
-p: 指定提示（prompt）。
-n: 指定要生成的最大 token 数量。

3.3. OpenAI 兼容服务器

llama.cpp 提供了一个内置的 HTTP 服务器，其 API 与 OpenAI 的 API 兼容。这使得它可以轻松地与 LangChain, LlamaIndex 等现有工具集成。

启动服务器：

./llama-server -m models/7B/ggml-model-q4_0.gguf -c 4096

然后，你可以像调用 OpenAI API 一样向 http://localhost:8080/v1/chat/completions 发送请求。

4. 高级功能

4.1. 投机性解码 (Speculative Decoding)

这是一种先进的推理优化技术，通过使用一个小的"草稿"模型来预测主模型的输出，从而显著加速生成速度。

工作原理: 草稿模型快速生成一个 token 序列草稿，然后由主模型一次性验证整个序列。如果验证通过，就可以节省逐个生成 token 的时间。
使用方法: 在 llama-cli 或 llama-server 中使用 --draft-model 参数指定一个小的、快速的草稿模型。

4.2. LoRA 支持

LoRA (Low-Rank Adaptation) 允许在不修改原始模型权重的情况下，通过训练一个小的适配器来微调模型的行为。llama.cpp 支持在推理时加载一个或多个 LoRA 适配器。

./llama-cli -m base-model.gguf --lora lora-adapter.gguf

甚至可以为不同的 LoRA 适配器设置不同的权重：

./llama-cli -m base.gguf --lora-scaled lora_A.gguf 0.5 --lora-scaled lora_B.gguf 0.5

4.3. 文法约束 (Grammars)

文法约束是一个非常强大的功能，它允许你强制模型的输出遵循特定的格式，例如严格的 JSON 模式。

格式: 使用一种名为 GBNF (GGML BNF) 的格式来定义语法规则。
应用: 在 API 请求中通过 grammar 参数提供 GBNF 规则，可以确保模型返回格式正确、可直接解析的 JSON 数据，避免了输出格式错误和繁琐的后处理。

示例： 使用 Pydantic 模型生成 JSON Schema，然后转换为 GBNF，以确保模型输出符合预期的 Python 对象结构。

import json
from typing import List
from pydantic import BaseModel
class QAPair(BaseModel):
question: str
answer: str
class Summary(BaseModel):
key_facts: List[str]
qa_pairs: List[QAPair]
# 生成 JSON Schema 并打印
schema = Summary.model_json_schema()
print(json.dumps(schema, indent=2))

5. 生态系统

llama.cpp 的成功催生了一个充满活力的生态系统：

llama-cpp-python: 最流行的 Python 绑定，提供了与 llama.cpp 几乎所有功能的接口，并与 LangChain、LlamaIndex 等框架深度集成。
Ollama: 一个将模型打包、分发和运行的工具，底层使用了 llama.cpp，极大地简化了在本地运行 LLM 的流程。
众多 UI 工具: 社区开发了大量的图形界面工具，让非技术用户也能轻松地与本地模型进行交互。

6. 总结

llama.cpp 不仅仅是一个推理引擎，它已经成为推动 LLM 本地化和大众化的关键力量。通过其卓越的性能、对资源的高度优化以及不断扩展的功能集（如多模态、文法约束），llama.cpp 为开发者和研究人员提供了一个强大而灵活的平台，让他们能够在各种设备上探索和部署 AI 应用，开启了低成本、保护隐私的本地 AI 新时代。