Ollama 使用指南

Ollama 是一个本地部署的开源 LLM 运行框架，支持在本地运行 Llama、Mistral、Gemma 等多种开源模型，提供数据隐私保护和无网络依赖的本地推理能力。

模型概览

推荐模型

模型	上下文	特色	适用场景
llama3	128K	Meta 开源旗舰	通用对话、复杂推理
llama3.2	128K	最新版本、性能优化	多场景通用
mistral	32K	平衡性能和速度	代码生成、通用任务
gemma2	8K	Google 开源	轻量级任务
qwen2	32K	阿里开源、中文优化	中文场景
codegemma	8K	代码专项	代码生成、补全
llava	-	多模态（仅图片）	图文理解

模型选择建议

from tfrobot.brain.chain.llms import Ollama

# 通用场景（推荐）
llm = Ollama(model="llama3")

# 中文场景
llm = Ollama(model="qwen2")

# 代码生成
llm = Ollama(model="codegemma")

# 多模态（仅支持图片）
llm = Ollama(model="llava")

安装与配置

安装 Ollama

1. 下载安装 Ollama

# macOS
brew install ollama

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

# Windows
# 从 https://ollama.com/download 下载安装程序

1. 启动 Ollama 服务

ollama serve

1. 拉取模型

# 拉取 Llama 3
ollama pull llama3

# 拉取其他模型
ollama pull mistral
ollama pull qwen2

配置参数

from tfrobot.brain.chain.llms import Ollama

llm = Ollama(
    model="llama3",
    base_url="http://localhost:11434",  # Ollama 服务地址
    timeout=120.0,                      # 请求超时时间
    num_ctx=64000,                      # 上下文长度（默认 64K）
    temperature=0.7,                    # 0.0-1.0，控制随机性
    top_p=0.9,                          # 0.0-1.0，核采样
    top_k=40,                           # 1-∞，top-k 采样
    num_gpu=-1,                         # GPU 层数（-1 = 使用所有可用 GPU）
    num_thread=8,                       # CPU 线程数
)

基础使用

简单对话

from tfrobot.brain.chain.llms import Ollama
from tfrobot.schema.message.conversation.message_dto import TextMessage

llm = Ollama(model="llama3")

result = llm.complete(
    current_input=TextMessage(content="你好，请介绍一下你自己")
)

print(result.generations[0].text)

流式输出

llm = Ollama(
    model="llama3",
    stream=True
)

result = llm.complete(
    current_input=TextMessage(content="写一首关于春天的诗")
)

# result.generations[0].text 会逐步生成

工具调用

原生模式

from tfrobot.brain.chain.llms import OllamaWithTools
from tfrobot.brain.chain.prompt.tool_prompt import ToolPrompt
from tfrobot.drive.tool.tool import tool

@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气"""
    return f"{city} 今天晴天，温度 25°C"

llm = OllamaWithTools(model="llama3")
llm.system_msg_prompt = [ToolPrompt()]

result = llm.complete(
    current_input=TextMessage(content="北京今天的天气怎么样？"),
    tools=[get_weather]
)

Ollama vs OllamaWithTools

• Ollama：基础模型，需要手动配置 ToolPrompt
• OllamaWithTools：预配置 ToolPrompt，更方便

# 方式一：使用 Ollama
llm = Ollama(model="llama3")
llm.system_msg_prompt.append(ToolPrompt())

# 方式二：使用 OllamaWithTools（推荐）
llm = OllamaWithTools(model="llama3")

多模态支持

注意：Ollama 仅支持图片多模态（llava 模型），不支持音频、视频和 PDF。

图片理解

from tfrobot.schema.message.conversation.message_dto import MultiPartMessage
from tfrobot.schema.message.msg_part import TextPart, ImagePart

# 使用 llava 模型
llm = Ollama(model="llava")

msg = MultiPartMessage(content=[
    TextPart(text="这张图片里有什么？"),
    ImagePart(
        image_url=ImgUrl(url="path/to/image.jpg"),
    ),
])

result = llm.complete(current_input=msg)

高级配置

GPU 加速

# 使用所有可用 GPU
llm = Ollama(
    model="llama3",
    num_gpu=-1  # 使用所有 GPU
)

# 使用指定 GPU 层数
llm = Ollama(
    model="llama3",
    num_gpu=4  # 使用 4 层 GPU
)

# 禁用 GPU（纯 CPU）
llm = Ollama(
    model="llama3",
    num_gpu=0
)

上下文长度

# 设置上下文长度
llm = Ollama(
    model="llama3",
    num_ctx=128000  # 128K tokens
)

批处理大小

llm = Ollama(
    model="llama3",
    num_batch=512  # 批处理大小
)

重复惩罚

llm = Ollama(
    model="llama3",
    repeat_penalty=1.1  # 重复惩罚（1.0 = 无惩罚）
)

性能优化

模型量化

Ollama 自动使用量化模型以减少内存占用：

# Ollama 默认使用 4-bit 量化
# 如需更高精度，可以拉取其他量化版本

# 拉取 8-bit 量化版本
# ollama pull llama3:8b-instruct-q8_0

内存优化

import psutil

# 根据可用内存调整参数
available_memory_gb = psutil.virtual_memory().available / (1024**3)

if available_memory_gb < 8:
    # 低内存配置
    llm = Ollama(
        model="llama3",
        num_ctx=32000,
        num_gpu=0  # 使用 CPU
    )
else:
    # 高内存配置
    llm = Ollama(
        model="llama3",
        num_ctx=128000,
        num_gpu=-1  # 使用所有 GPU
    )

并行处理

import asyncio

async def batch_process(llm, inputs):
    tasks = [llm.async_complete(current_input=inp) for inp in inputs]
    results = await asyncio.gather(*tasks)
    return results

上下文管理

上下文压缩

当上下文超出限制时，Chain 会自动触发压缩：

# Chain 自动处理
from tfrobot.brain.chain import SingleChain

chain = SingleChain(llm=llm)
result = chain.run(input_message=user_input)

手动压缩

try:
    result = llm.complete(current_input=user_input)
except Exception as e:
    if "context" in str(e).lower():
        # 手动压缩
        compacted, _, _, _, _ = llm.collapse_context(
            current_input=user_input,
            conversation=conversation,
            to_size=30000
        )
        result = llm.complete(current_input=user_input, conversation=compacted)

错误处理

常见错误

错误类型	原因	解决方案
ConnectionError	Ollama 服务未启动	运行 ollama serve
ModelNotFound	模型未拉取	运行 ollama pull <model>
ContextLengthExceeded	上下文超长	使用 Chain 的 compact 功能
OutOfMemory	内存不足	减少上下文长度或使用量化模型

手动错误处理

import requests

try:
    result = llm.complete(current_input=user_input)
except requests.exceptions.ConnectionError:
    print("Ollama 服务未启动，请运行: ollama serve")
except Exception as e:
    if "model" in str(e).lower() and "not found" in str(e).lower():
        print(f"模型未找到，请运行: ollama pull {llm.model}")
    elif "memory" in str(e).lower():
        print("内存不足，请尝试减少上下文长度或使用量化模型")
    else:
        raise

最佳实践

1. Temperature 设置

# 需要创造性（如写作）
llm = Ollama(model="llama3", temperature=1.0)

# 需要稳定性（如代码生成）
llm = Ollama(model="llama3", temperature=0.0)

2. Prompt 工程

llm.system_msg_prompt = [
    MemoPrompt(template="你是一个专业的 Python 开发者。"),
    ToolPrompt(),
]

llm.after_input_msg_prompt = [
    MemoPrompt(template="请使用 Markdown 格式回复，代码块标明语言。"),
]

3. 选择合适的模型

# 根据任务选择模型
def get_llm_for_task(task_type: str) -> Ollama:
    if task_type == "code":
        return Ollama(model="codegemma")
    elif task_type == "chinese":
        return Ollama(model="qwen2")
    elif task_type == "vision":
        return Ollama(model="llava")
    else:
        return Ollama(model="llama3")

4. 监控资源使用

import psutil

def check_resources():
    """检查系统资源"""
    cpu_percent = psutil.cpu_percent()
    memory = psutil.virtual_memory()

    print(f"CPU 使用率: {cpu_percent}%")
    print(f"内存使用率: {memory.percent}%")
    print(f"可用内存: {memory.available / (1024**3):.2f} GB")

check_resources()

5. 使用 Docker 部署

# 使用 Docker 运行 Ollama
docker run -d \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

# 拉取模型
docker exec -it ollama ollama pull llama3

数据隐私与安全

本地部署优势

1. 数据隐私：所有数据在本地处理，不会上传到云端
2. 无网络依赖：无需互联网连接即可使用
3. 完全控制：可以修改和微调模型
4. 成本为零：无需支付 API 费用

安全建议

# 敏感数据处理
llm = Ollama(model="llama3")

# 敏感数据在本地处理，不会泄露
sensitive_data = "用户的敏感信息"
result = llm.complete(
    current_input=TextMessage(content=f"分析以下数据：{sensitive_data}")
)

相关文档

• BaseLLM 基类详解
• ChatLLM 对话模型
• 工具调用详解
• Ollama 官方文档
• Ollama 模型库