Ollama 教程

2. Modelfile 创建模型

# Modelfile
FROM llama3
SYSTEM "你是一个友好的中文助手"
PARAMETER temperature 0.7
PARAMETER num_ctx 4096

# 创建
ollama create my-helper -f Modelfile

# 使用
ollama run my-helper

3. 查看模型详情

ollama show llama3

# 输出示例
# Model
#   architecture        llama
#   parameters          8.0B
#   context length      8192
#   embedding length    4096
#   quantization        Q4_0

# 查看模板
ollama show llama3 --template

# 查看参数
ollama show llama3 --parameters

4. 常用环境变量

OLLAMA_HOST          服务地址(默认 127.0.0.1:11434)
OLLAMA_MODELS        模型存储目录
OLLAMA_KEEP_ALIVE    模型驻留时间
OLLAMA_NUM_PARALLEL  并行请求数
OLLAMA_MAX_LOADED_MODELS  最多加载模型数

Ollama 基本概念

Ollama 基本概念

1. 模型(Models)

# 模型 = 权重 + 配置 + 模板
# 存储在 ~/.ollama/models

# 模型命名: name:tag
ollama run llama3:8b
ollama run qwen2.5:7b-instruct

# tag 常见值
latest   默认最新
7b/8b/14b/70b   参数规模
q4_0/q8_0/fp16  量化级别
instruct/chat   是否指令微调

2. 量化(Quantization)

# 量化:压缩模型精度,减小体积,加快推理
# 权衡:精度 vs 速度/内存

q4_0    4bit,最常用,体积小
q4_K_M  4bit K-quant,质量更好
q5_K_M  5bit,质量接近原版
q8_0    8bit,质量高,体积较大
f16     全精度,最大最准

# 例如 qwen2.5:7b
# 原始 f16 约 15GB
# q4_K_M 约 4.7GB(常用)

3. 上下文长度(Context)

# 上下文:模型一次能"记住"的 token 数
# 越长能处理更长对话/文档,但更耗内存

# 运行时设置
ollama run llama3 --num-ctx 16384

# Modelfile 设置
PARAMETER num_ctx 8192

# API 设置
{"options": {"num_ctx": 8192}}

4. 推理参数

temperature    温度(0-2),越高越随机
top_p          核采样,概率阈值
top_k          候选数
max_tokens     最大生成 token
repeat_penalty 重复惩罚
seed           随机种子

# 用途
temperature 0.1  确定性输出(代码/事实)
temperature 0.8  创造性输出(写作/头脑风暴)

Ollama 模型交互

Ollama 模型交互

1. 交互式对话

# 启动交互模式
ollama run qwen2.5

# >>> 你好,介绍一下你自己
# 你好!我是通义千问...

# 多行输入
# >>> 写一首诗
# ...回车后按 \\ 再回车

# 查看会话命令
/help       帮助
/?          参数列表
/set        设置(如 temperature)
/bye        退出
/save <名>  保存会话

2. 单次调用(非交互)

# 管道输入
echo "翻译成英文:你好" | ollama run qwen2.5

# 直接传参
ollama run qwen2.5 "用一句话介绍 Python"

# 从文件读取
cat prompt.txt | ollama run qwen2.5

3. 系统提示词

# Modelfile 方式
FROM qwen2.5
SYSTEM "你是一个专业的中文技术文档翻译者"

# 交互式设置
# /set system 你是一个...助手

# API 方式
{
  "messages": [
    {"role": "system", "content": "你是...助手"},
    {"role": "user", "content": "你好"}
  ]
}

4. 多模态交互(如 llava)

# 图片模型
ollama run llava

# 描述图片
# 交互中输入图片路径
# >>> /image ./photo.png
# >>> 这张图里有什么?

# 或命令行
ollama run llava "描述图片" < ./photo.png

Ollama API 交互

Ollama API 交互

1. REST API 概览

# Ollama 内置 HTTP API,默认端口 11434

# 端点
POST /api/generate        文本生成
POST /api/chat            对话(推荐)
POST /api/embed            嵌入向量
GET  /api/tags             模型列表
POST /api/show             模型详情
POST /api/pull             拉取模型
POST /api/create           创建模型
DELETE /api/delete         删除模型

2. 对话 API(OpenAI 兼容)

# OpenAI 兼容端点
# POST /v1/chat/completions

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5",
    "messages": [
      {"role": "system", "content": "你是助手"},
      {"role": "user", "content": "你好"}
    ]
  }'

# 返回
# {
#   "choices": [{"message": {"content": "你好!..."}}]
# }

3. /api/generate

curl http://localhost:11434/api/generate \
  -d '{
    "model": "qwen2.5",
    "prompt": "讲个笑话",
    "stream": false,
    "options": {"temperature": 0.8}
  }'

# 流式输出
curl http://localhost:11434/api/generate \
  -d '{"model": "qwen2.5",
       "prompt": "写一段代码",
       "stream": true}'
# 返回多行 JSON,每行一个 token 片段

4. /api/chat

curl http://localhost:11434/api/chat \
  -d '{
    "model": "qwen2.5",
    "messages": [
      {"role": "user", "content": "1+1=?"}
    ],
    "stream": false
  }'

# 多轮对话:把历史消息都传过去

5. 嵌入与向量

# 生成文本嵌入向量(用于 RAG/向量检索)
curl http://localhost:11434/api/embed \
  -d '{
    "model": "nomic-embed-text",
    "input": "你好世界"
  }'

# 返回 768 维向量
# {"embeddings": [[0.123, ...]]}

Ollama Python 使用

Ollama Python 使用

1. 安装客户端

# 官方 Python 库
pip install ollama

# 或 OpenAI SDK(兼容)
pip install openai

2. 基本对话

import ollama

# 同步对话
response = ollama.chat(
    model="qwen2.5",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)
print(response["message"]["content"])

# 多轮对话
messages = [
    {"role": "system", "content": "你是助手"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好!"},
    {"role": "user", "content": "今天天气如何?"}
]
resp = ollama.chat(model="qwen2.5", messages=messages)
print(resp["message"]["content"])

3. 流式输出

import ollama

stream = ollama.chat(
    model="qwen2.5",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True,
)

for chunk in stream:
    print(chunk["message"]["content"], end="", flush=True)

4. OpenAI SDK 方式

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"    # 任意值
)

resp = client.chat.completions.create(
    model="qwen2.5",
    messages=[{"role": "user", "content": "你好"}]
)
print(resp.choices[0].message.content)

5. 实用封装

import ollama

class LocalLLM:
    def __init__(self, model="qwen2.5"):
        self.model = model
        self.messages = []

    def system(self, content):
        self.messages.append(
            {"role": "system", "content": content})

    def ask(self, content):
        self.messages.append(
            {"role": "user", "content": content})
        resp = ollama.chat(
            model=self.model, messages=self.messages)
        answer = resp["message"]["content"]
        self.messages.append(
            {"role": "assistant", "content": answer})
        return answer

llm = LocalLLM("qwen2.5")
llm.system("你是一个 Python 导师")
print(llm.ask("什么是装饰器?"))
print(llm.ask("给个例子"))

Ollama Open WebUI

Ollama Open WebUI

1. 什么是 Open WebUI

Open WebUI 是开源的 LLM Web 界面,类似 ChatGPT 的交互体验,支持 Ollama、OpenAI 等后端,提供多用户、聊天管理、文档上传(RAG)、模型管理等功能。

2. Docker 安装

# 官方推荐 Docker 部署
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --name open-webui \
  ghcr.io/open-webui/open-webui:main

# 访问 http://localhost:3000
# 首次注册管理员账号

3. 本地安装(Python)

# 需要 Python 3.11+
git clone https://github.com/open-webui/open-webui.git
cd open-webui

# 前端构建
npm install && npm run build

# 后端
pip install -r requirements.txt
cd ./backend
python main.py

# 访问 http://localhost:8080

4. 主要功能

# 聊天界面
多会话管理、Markdown 渲染、代码高亮
模型切换、系统提示词、参数调节

# 多用户
注册/登录、用户管理、权限控制

# 知识库(RAG)
上传文档(PDF/Word/TXT),向量化检索

# 模型管理
查看/下载 Ollama 模型、自定义模型

# 其他
语音输入、图片理解、Web 搜索(需配置)

5. 配置 Ollama 连接

# Docker 方式
# OLLAMA_BASE_URL 指向 Ollama 服务

# 如果 Ollama 在宿主机
docker run ... -e OLLAMA_BASE_URL=http://host.docker.internal:11434

# 让 Ollama 监听所有接口
OLLAMA_HOST=0.0.0.0 ollama serve

Ollama Page Assist

Ollama Page Assist

1. 什么是 Page Assist

Page Assist 是浏览器扩展,把本地 LLM(Ollama)集成到浏览器中,可在任意网页侧边栏调用模型,实现网页内容问答、翻译、摘要等功能。

2. 安装

# 浏览器扩展
# Chrome/Edge: 搜索 "Page Assist" 安装
# https://chromewebstore.google.com/
# Firefox: AMO 商店搜索 "Page Assist"

# 或 GitHub 手动安装
# https://github.com/n4ze3m/page-assist

3. 配置

1. 打开扩展设置
2. Ollama API URL: http://localhost:11434
3. 选择默认模型(qwen2.5 等)
4. 配置侧边栏快捷键(如 Ctrl+Shift+L)

# 前提:Ollama 服务已启动
ollama serve

4. 功能

# 侧边栏聊天
# 在任意网页打开侧边栏与本地模型对话

# 网页内容问答
# 选中网页文本 → 右键 → 问模型

# 摘要/翻译
# 一键摘要网页、翻译选中内容

# 页面上下文
# 可让模型基于当前网页内容回答

# 历史记录
# 会话保存与管理

5. 使用场景

• 阅读长文时让模型总结要点
• 外文网页即时翻译
• 代码片段解释
• 研究资料问答(隐私安全)

Ollama 常见问题与资源

Ollama 常见问题与资源

1. 常见问题

# Q: 模型运行很慢?
# A: 用小参数模型(qwen2.5:1.5b)或开启 GPU

# Q: 内存不足 OOM?
# A: 用 4bit 量化版本,或减少 num_ctx

# Q: 下载模型失败?
# A: 检查网络,设置代理或镜像源

# Q: 端口被占用?
# A: 设置 OLLAMA_HOST 换端口

# Q: API 调用超时?
# A: 首次加载模型慢,增加超时时间

# Q: 中文输出乱码?
# A: 选中文模型(qwen2.5),或检查终端编码

2. 性能优化

# GPU 加速检查
ollama run llama3 --verbose
# 看 eval rate(每秒 token)

# 常用优化
1. 用量化模型(q4_K_M)
2. 减小 num_ctx(如 2048)
3. 关闭不用的模型(ollama rm)
4. 设置 OLLAMA_KEEP_ALIVE 控制驻留
5. 升级内存/GPU

3. 模型选择建议

# 通用对话
qwen2.5:7b(中文强) / llama3.1:8b

# 代码
deepseek-coder / codellama / qwen2.5-coder

# 数学推理
deepseek-r1 / qwen2.5-math

# 轻量设备
qwen2.5:1.5b / phi3:mini / llama3.2:3b

# 多模态
llava / qwen2.5-vl

4. 应用场景

• 本地知识库问答(RAG)
• 代码辅助与审查
• 文档摘要与翻译
• 私有数据智能分析
• 开发测试(替换 OpenAI API)

5. 学习资源

官网:      ollama.com
模型库:    ollama.com/library
GitHub:    github.com/ollama/ollama
文档:      github.com/ollama/ollama/tree/main/docs
社区:      reddit.com/r/ollama
Open WebUI: github.com/open-webui/open-webui
Page Assist: github.com/n4ze3m/page-assist

Ollama 总结与进阶

Ollama 总结与进阶

1. 知识回顾

• 安装运行:ollama run/pull/list 等基础命令
• 模型管理:量化选择、Modelfile 自定义、参数调优
• API 集成:REST API + OpenAI 兼容端点
• Python 开发:ollama 库与 OpenAI SDK
• 图形界面:Open WebUI、Page Assist

2. 进阶方向

• RAG 应用:Ollama + LangChain + 向量库(Chroma)
• Function Calling:让模型调用本地工具
• 微调:LoRA 微调专用模型
• 多模型路由:按任务选择模型
• Agent 开发:本地模型构建 AI 助手

3. RAG 示例(LangChain)

pip install langchain langchain-community chromadb

from langchain_community.llms import Ollama
from langchain_community.embeddings import OllamaEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

# 加载文档
loader = TextLoader("docs.txt")
docs = loader.load()

# 切分
splitter = RecursiveCharacterTextSplitter(chunk_size=500)
chunks = splitter.split_documents(docs)

# 向量化存储
embeddings = OllamaEmbeddings(model="nomic-embed-text")
db = Chroma.from_documents(chunks, embeddings)

# 检索问答
llm = Ollama(model="qwen2.5")
retriever = db.as_retriever()
query = "文档里说了什么?"
context = retriever.invoke(query)

from langchain.chains import RetrievalQA
qa = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
print(qa.invoke(query)["result"])

4. Function Calling 示例

import ollama

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }
}]

resp = ollama.chat(
    model="qwen2.5",
    messages=[{"role": "user",
               "content": "北京天气怎么样?"}],
    tools=tools,
)
print(resp["message"]["tool_calls"])

5. 结语

Ollama 降低了本地大模型的门槛,是个人开发者、隐私敏感行业和离线场景的理想选择。配合 RAG、Agent 等进阶技术,可以构建强大的本地 AI 应用。