Ollama 是一款支持本地运行大型语言模型（LLM）的开源工具，提供简单高效的模型管理、交互式对话和 API 集成能力。以下是其核心功能、参数详解及高级用法的完整总结。

---

一、安装与基础命令

1. 安装

• Windows：
  下载安装包 ollama.com/download，双击运行。
• macOS/Linux：

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

2. 模型管理

命令	说明	示例
ollama run <模型>	运行模型	ollama run llama3
ollama list	查看已下载模型	-
ollama pull <模型>	下载模型	ollama pull mistral:7b
ollama rm <模型>	删除模型	ollama rm codellama

---

二、核心参数详解

Ollama 的生成参数通过 options 字典传递，以下是关键参数说明：

参数	类型	作用	推荐值	示例
temperature	float	控制输出随机性（值越小越确定）	0.1-1.0	0.3（严谨回答） 0.8（创意生成）
num_predict	int	限制生成的最大 token 数	10-4096	256（限制生成长度）
top_p	float	核采样概率阈值（保留概率累加至该值的 token）	0.5-0.95	0.9（平衡多样性）
top_k	int	保留概率最高的前 k 个 token	20-100	40（限制候选词范围）
seed	int	随机种子（固定输出结果）	任意整数	42（可复现结果）
stop	list[str]	停止生成的条件符号	标点或关键词	["\n", "。"]（按句截断）

示例代码（参数使用）

import ollama

response = ollama.generate(
    model="llama3",
    prompt="写一篇关于火星殖民的短文",
    options={
        "temperature": 0.5,
        "top_p": 0.9,
        "num_predict": 300,
        "stop": ["\n", "。"]
    }
)

---

三、多轮对话实现

1. 上下文传递

通过维护 context 列表实现多轮对话：

# 第一轮对话
response1 = ollama.generate(
    model="mistral",
    prompt="你好，我叫小明",
)
context = response1["context"]

# 第二轮对话
response2 = ollama.generate(
    model="mistral",
    prompt="我刚才说我叫什么名字？",
    context=context  # 传递上下文
)
print(response2["response"])  # 输出：你叫小明

2. 自动上下文管理

使用 ChatHandler 类简化流程：

from ollama import AsyncClient

async def chat_session():
    client = AsyncClient()
    messages = [{"role": "user", "content": "推荐一部科幻电影"}]
    
    async for reply in await client.chat(model="llama3", messages=messages, stream=True):
        print(reply["message"]["content"], end="", flush=True)
        messages.append(reply["message"])  # 自动更新上下文

---

四、流式处理与非流式处理

1. 流式处理（逐字输出）

• 优势：实时性强，适合长文本生成。
• 实现方式：

方式一：使用 ollama 库

response = ollama.generate(
    model="phi3",
    prompt="实时解说足球比赛",
    stream=True
)

for chunk in response:
    print(chunk["response"], end="", flush=True)  # 逐词输出

方式二：HTTP 原生流式

import requests

url = "http://localhost:11434/api/generate"
payload = {
    "model": "mistral",
    "prompt": "生成一篇气候报告",
    "stream": True
}

with requests.post(url, json=payload, stream=True) as res:
    for line in res.iter_lines():
        if line:
            chunk = json.loads(line.decode())
            print(chunk.get("response", ""), end="", flush=True)

2. 非流式处理（一次性返回）

• 优势：代码简单，适合短文本。
• 示例：

response = ollama.generate(
    model="llama3",
    prompt="用一句话解释相对论"
)
print(response["response"])  # 一次性输出完整结果

---

五、返回 JSON 格式的优化

1. 强制 JSON 输出的方法

方法一：系统提示 + 参数控制

system_prompt = """
你必须返回严格符合以下 JSON 格式的数据：
{
  "method": "check",
  "params": {"vendor": "huawei"|"cisco"|"all"}
}
规则：
1. vendor 必须全小写
2. 禁止添加额外字段
"""

response = ollama.generate(
    model="mistral",
    system=system_prompt,
    format="json",  # 关键参数
    options={"temperature": 0.1}
)

方法二：后处理校验

import json

try:
    data = json.loads(response["response"])
    assert "method" in data, "Missing required field: method"
except (json.JSONDecodeError, AssertionError) as e:
    print(f"Invalid JSON: {e}")

2. 高级校验技巧

• 正则表达式匹配：

  import re
  json_pattern = re.compile(r'\{.*?"method": "check".*?\}')
  if not json_pattern.match(response["response"]):
      print("JSON 格式不匹配")
  

• Schema 验证（使用 jsonschema 库）：

  from jsonschema import validate
  
  schema = {
      "type": "object",
      "properties": {
          "method": {"type": "string", "enum": ["check"]},
          "params": {
              "type": "object",
              "properties": {"vendor": {"type": "string", "enum": ["huawei", "cisco", "all"]}},
              "required": ["vendor"]
          }
      },
      "required": ["method", "params"]
  }
  
  validate(instance=data, schema=schema)
  

---

六、性能优化与调试

1. 硬件加速

• NVIDIA GPU：

  OLLAMA_GPU=1 ollama run llama3 --gpu
  

• Apple Silicon：

  OLLAMA_METAL=1 ollama run mistral
  

2. 内存优化

• 量化模型：使用 4-bit 或 8-bit 量化版本

  ollama run llama3:8b-q4_0
  

• 限制上下文长度：

  options={"num_ctx": 2048}  # 默认 4096
  

3. 调试技巧

• 日志记录：

  ollama serve --log-level debug
  

• 响应分析：

  print(f"生成耗时：{response['eval_duration']/1e9:.2f}s")
  print(f"总 token 数：{response['eval_count']}")
  

---

七、完整代码示例

场景：构建一个天气查询 API，返回结构化 JSON

import ollama
import json
from typing import Dict

def get_weather(city: str) -> Dict:
    """调用模型生成结构化天气数据"""
    system = '''
    你是一个天气助手，必须返回以下 JSON 格式：
    {
        "city": "城市名称",
        "temperature": "温度（摄氏度）",
        "condition": "天气状况"
    }
    规则：
    1. temperature 必须是数字
    2. condition 只能是 "晴/雨/多云/雪"
    '''
    
    response = ollama.generate(
        model="mistral",
        prompt=f"查询{city}的天气",
        system=system,
        format="json",
        options={
            "temperature": 0.1,
            "stop": ["\n", "}"],  # 确保 JSON 闭合
            "num_predict": 100
        }
    )
    
    try:
        data = json.loads(response["response"])
        data["temperature"] = float(data["temperature"])  # 类型转换
        return data
    except (json.JSONDecodeError, KeyError, ValueError) as e:
        return {"error": f"解析失败: {str(e)}"}

# 使用示例
print(get_weather("北京"))  # 输出: {'city': '北京', 'temperature': 22.5, 'condition': '晴'}

---

八、常见问题解决

问题	解决方案
模型返回非 JSON	1. 降低 temperature 2. 添加更详细的格式示例
生成内容截断	增大 num_predict 值
响应速度慢	1. 使用量化模型 2. 启用 GPU 加速
中文输出不稳定	添加 stop 参数：["。", "\n"]

---

通过本指南，您可掌握 Ollama 的完整工作流，从基础对话到生产级结构化数据生成。建议结合自身需求调整参数，并通过 ollama pull <模型> 探索更多模型能力。