1. Ollama 详细介绍

1.1 什么是 Ollama

Ollama 是一个开源的本地大语言模型运行与管理工具，并非大语言模型本身。它就像是大模型领域的 Docker，通过极简的操作逻辑，让没有 AI 技术背景的普通用户也能在个人电脑上轻松运行各类开源大模型。

  • 开发语言：Go 语言
  • 许可证：MIT 开源许可证
  • 核心定位：让大模型从云端走向本地，实现隐私化、离线化、低成本的 AI 应用
  • GitHub 星标：截至 2026 年 4 月，已超过 150K，是全球最活跃的开源项目之一

1.2 核心特性

  1. 一键部署：一条命令即可下载并运行模型，无需手动配置环境、转换模型格式
  2. 完全本地运行：所有数据在本机处理，不经过云端服务器，隐私安全有保障
  3. 跨平台支持：完美支持 Windows、macOS、Linux 三大操作系统
  4. 自动硬件加速：自动识别并调用 NVIDIA GPU、AMD GPU、Apple Silicon 进行加速
  5. 丰富的模型库：支持 Llama 3、Qwen、DeepSeek、Mistral、Gemma 等几乎所有主流开源大模型
  6. 标准化 API：提供 REST API 接口，方便开发者集成到自己的应用中
  7. 模型管理：轻松下载、删除、查看本地模型，支持模型版本管理

1.3 工作原理

Ollama 的工作流程主要分为三个核心步骤：

  1. 模型加载

    • 用户通过 ollama pull <model> 命令下载模型（GGUF 格式，包含量化权重）
    • 模型存储在本地缓存（Windows 默认路径：C:\Users\用户名\.ollama\models）
    • 加载时自动根据硬件选择合适的推理后端（基于 llama.cpp）

  2. 推理过程

    • 预处理：将输入提示词分词，转换为模型输入张量
    • 推理：使用优化的 GGUF 解码引擎执行 Transformer 前向传播
    • 优化：通过量化技术减少内存消耗，利用 KV Cache 加速生成
    • 输出：逐 token 生成结果，支持流式输出

  3. 服务与交互

    • CLI：通过 ollama run 提供交互式终端
    • API：启动本地服务器（默认地址：http://localhost:11434）

1.4 支持的主流模型

模型名称 参数大小 推荐配置 特点
Llama 3.2 1B/3B/7B/13B 8GB+内存 Meta 最新模型，性能均衡，多语言支持好
Qwen 2.5 0.5B/1.8B/7B/14B 8GB+内存 阿里通义千问开源版，中文能力优秀
DeepSeek R1 7B/14B 16GB+内存 推理能力强，适合数学和代码任务
Mistral 7B/8x7B 8GB+内存 轻量高效，速度快
Gemma 2 2B/9B 8GB+内存 Google 出品，安全可靠

新手推荐：Qwen 2.5:7B（中文能力最好）或 Llama 3.2:7B（综合性能最佳）

1.5 优缺点分析

优点：

  • ✅ 极低门槛：无需复杂配置，一键安装运行
  • ✅ 隐私安全：数据完全本地处理，适合敏感信息
  • ✅ 离线可用：无需网络连接也能使用
  • ✅ 免费开源：无使用限制，可自由二次开发
  • ✅ 硬件友好：普通笔记本电脑也能流畅运行 7B 级模型
  • ✅ 生态丰富：有大量第三方工具和前端支持

缺点：

  • ❌ 性能上限：受限于本地硬件，无法与云端大模型相比
  • ❌ 模型大小限制：大参数模型（如 70B+）需要高端显卡才能运行
  • ❌ 功能单一：主要专注于文本生成，不支持多模态（部分模型除外）
  • ❌ 更新依赖：模型更新需要手动拉取
  • ❌ 中文支持参差不齐：部分国外模型中文能力较弱

2. Windows 系统安装与配置

2.1 系统要求

  • 操作系统：Windows 10 1903 及以上版本或 Windows 11
  • 内存：最低 8GB（推荐 16GB 及以上）
  • 硬盘：至少 10GB 可用空间（每个 7B 模型约 4-6GB）
  • 显卡（可选）：NVIDIA 显卡（支持 CUDA）或 AMD 显卡（支持 ROCm）

2.2 在线安装步骤

  1. 下载安装包

    • 访问 Ollama 官网：https://ollama.com/
    • 点击 “Download for Windows” 按钮
    • 下载 OllamaSetup.exe 安装包

  2. 运行安装程序

    • 双击下载的 OllamaSetup.exe
    • 点击 “Install” 开始安装
    • 等待安装完成（通常 1-2 分钟）
    • 点击 “Finish” 结束安装

  3. 确认服务启动

    • 安装完成后，Ollama 服务会自动启动
    • 查看系统托盘（右下角）是否出现羊驼图标
    • 如果没有出现，手动在开始菜单中找到并运行 “Ollama”

2.3 安装后验证

  1. 打开终端

    • 按下 Win + R，输入 cmd 或 powershell，回车
    • 或者右键点击开始菜单，选择 “Windows 终端”

  2. 验证安装

    • 在终端中输入以下命令： 
      ollama --version
    • 如果显示类似以下内容，说明安装成功： 
      ollama version 0.1.48

  3. 测试运行

    • 输入以下命令运行一个简单模型： 
      ollama run gemma:2b
    • 等待模型下载完成（约 1.5GB）
    • 输入 “你好” 测试是否能正常回复

2.4 常见安装问题与解决方案

问题 1：终端输入 ollama 提示"不是内部或外部命令"

原因：安装时没有自动添加到系统环境变量

解决方案：

  1. 重启终端（CMD/PowerShell）
  2. 如果问题依旧，重新安装 Ollama，确保安装时勾选 “Add to PATH”
  3. 手动添加环境变量：
    • 右键点击"此电脑" → “属性” → “高级系统设置” → “环境变量”
    • 在"系统变量"中找到 “Path”，点击"编辑"
    • 添加 Ollama 安装路径（默认：C:\Program Files\Ollama）
    • 点击"确定"保存，重启终端

问题 2：Error: ollama server not responding

原因：Ollama 服务没有正常启动

解决方案：

  1. 检查系统托盘是否有 Ollama 图标
  2. 如果没有，手动启动：在开始菜单中找到并运行 “Ollama”
  3. 或者在终端中输入： 
    ollama serve
  4. 检查端口 11434 是否被占用： 
    netstat -ano | findstr :11434
  5. 如果被占用，关闭占用端口的程序或重启电脑

问题 3：模型下载速度慢或失败

解决方案：

  1. 多次尝试：退出下载后重新执行 ollama pull <model>
  2. 使用国内镜像源（推荐）：
    • 设置环境变量： 
      set OLLAMA_HOST=https://ollama.fly.dev
    • 然后再拉取模型
  3. 离线下载：
    • 从第三方网站下载 GGUF 格式的模型文件
    • 使用 ollama create 命令导入本地模型

问题 4：运行模型时提示"内存不足"

解决方案：

  1. 关闭其他占用内存的程序
  2. 选择更小的模型（如 gemma:2b 或 qwen2.5:1.8b）
  3. 选择量化程度更高的版本（如 q4_K_M）： 
    ollama pull qwen2.5:7b-q4_K_M
  4. 增加虚拟内存：
    • 右键点击"此电脑" → “属性” → “高级系统设置” → “高级” → “性能设置” → “高级” → “虚拟内存”
    • 将虚拟内存大小设置为物理内存的 1.5-2 倍

问题 5：Windows 启动失败，提示缺少 Microsoft C++ 运行库

解决方案：

  • 下载并安装 Microsoft Visual C++ Redistributable：
    https://aka.ms/vs/17/release/vc_redist.x64.exe

3. 基础使用教程

3.1 命令行基本操作

Ollama 的所有操作都可以通过命令行完成，以下是最常用的命令：

命令 说明 示例
ollama --version 查看版本信息 ollama --version
ollama help 查看帮助信息 ollama help
ollama serve 手动启动 Ollama 服务 ollama serve
ollama ps 查看正在运行的模型 ollama ps
ollama stop <model> 停止正在运行的模型 ollama stop qwen2.5:7b

3.2 下载与管理模型

  1. 下载模型

    # 下载最新版本的模型
ollama pull qwen2.5:7b

# 下载指定版本或量化版本
ollama pull qwen2.5:7b-q4_K_M

  2. 查看本地模型

    ollama list

    输出示例：

    NAME            ID              SIZE    MODIFIED
qwen2.5:7b      78e26419910c    4.7 GB  2 hours ago
gemma:2b        5f93624f8e1d    1.5 GB  1 day ago

  3. 查看模型详情

    ollama inspect qwen2.5:7b

  4. 删除模型

    ollama rm gemma:2b

3.3 与模型进行对话

  1. 启动交互式对话

    ollama run qwen2.5:7b

  2. 在对话中使用命令

    • /help：查看可用命令
    • /list：列出本地模型
    • /set <parameter> <value>：设置参数
    • /show <info>：显示模型信息
    • /bye：退出对话

  3. 一次性执行

    ollama run qwen2.5:7b "用一句话介绍人工智能"

4. 常用示例与 Demo

4.1 命令行对话示例

示例 1：简单问答

ollama run qwen2.5:7b
>>> 你好，请介绍一下你自己
我是 Qwen 2.5，由阿里巴巴开发的开源大语言模型。我可以帮助你回答问题、写作、翻译、编程等。有什么我可以帮你的吗？

>>> 请解释一下什么是机器学习
机器学习是人工智能的一个分支，它使计算机系统能够从数据中学习并改进，而无需进行明确的编程。
...

>>> /bye

示例 2：代码生成

ollama run qwen2.5:7b
>>> 用 Python 写一个快速排序算法

示例 3：文本翻译

ollama run qwen2.5:7b
>>> 将下面的英文翻译成中文：Artificial intelligence is the future of technology.

4.2 Python API 调用示例

Ollama 提供了 REST API 接口，可以方便地用 Python 调用。

准备工作：

# 安装 requests 库
pip install requests

示例 1：基础单轮对话（非流式）

import requests
import json

# Ollama 本地 API 地址
OLLAMA_API_URL = "http://localhost:11434/api/generate"

def ask_ollama(prompt, model="qwen2.5:7b"):
    """
    向 Ollama 发送问题并获取完整回答
    """
    payload = {
        "model": model,
        "prompt": prompt,
        "stream": False  # 不流式输出，一次性返回结果
    }
    
    response = requests.post(OLLAMA_API_URL, json=payload)
    result = response.json()
    
    return result["response"]

# 测试
if __name__ == "__main__":
    answer = ask_ollama("用一句话介绍你自己")
    print(answer)

示例 2：流式输出（实时显示）

import requests
import json

def ask_ollama_stream(prompt, model="qwen2.5:7b"):
    """
    流式输出，实时显示回答
    """
    payload = {
        "model": model,
        "prompt": prompt,
        "stream": True  # 开启流式输出
    }
    
    response = requests.post(OLLAMA_API_URL, json=payload, stream=True)
    
    for line in response.iter_lines():
        if line:
            data = json.loads(line)
            print(data.get("response", ""), end="", flush=True)
    
    print()  # 换行

# 测试
if __name__ == "__main__":
    ask_ollama_stream("写一个关于春天的短诗")

示例 3：多轮对话（带上下文记忆）

import requests
import json

OLLAMA_API_URL = "http://localhost:11434/api/chat"

class OllamaChatbot:
    def __init__(self, model="qwen2.5:7b"):
        self.model = model
        self.history = []  # 保存对话历史
    
    def chat(self, message):
        """
        发送消息并获取回复
        """
        # 添加用户消息到历史
        self.history.append({"role": "user", "content": message})
        
        payload = {
            "model": self.model,
            "messages": self.history,
            "stream": False
        }
        
        response = requests.post(OLLAMA_API_URL, json=payload)
        result = response.json()
        
        # 添加 AI 回复到历史
        assistant_message = result["message"]["content"]
        self.history.append({"role": "assistant", "content": assistant_message})
        
        return assistant_message

# 测试
if __name__ == "__main__":
    bot = OllamaChatbot()
    
    print("AI: 你好！我是你的 AI 助手，有什么可以帮你的吗？")
    
    while True:
        user_input = input("你: ")
        
        if user_input.lower() in ["退出", "bye", "再见"]:
            print("AI: 再见！")
            break
        
        response = bot.chat(user_input)
        print(f"AI: {response}")

4.3 实用场景示例

示例 1：文本总结

def summarize_text(text, model="qwen2.5:7b"):
    prompt = f"""请用简洁的语言总结下面的文本，不超过100字：
    
    {text}
    """
    
    return ask_ollama(prompt, model)

# 测试
long_text = """
人工智能（Artificial Intelligence，简称AI）是一门旨在使计算机系统能够模拟、延伸和扩展人类智能的技术科学。
它研究和开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统。人工智能的研究领域包括机器学习、
自然语言处理、计算机视觉、专家系统、机器人学等。近年来，随着深度学习技术的发展，人工智能取得了突破性进展，
在图像识别、语音识别、自然语言处理等领域达到了甚至超越了人类的水平。人工智能正在深刻地改变着我们的生活、
工作和学习方式，成为推动社会发展的重要力量。
"""

summary = summarize_text(long_text)
print("总结：", summary)

示例 2：代码解释

def explain_code(code, model="qwen2.5:7b"):
    prompt = f"""请详细解释下面这段 Python 代码的功能和每一行的作用：
    
    ```python
    {code}
    ```
    """
    
    return ask_ollama(prompt, model)

# 测试
code = """
def fibonacci(n):
    if n <= 1:
        return n
    else:
        return fibonacci(n-1) + fibonacci(n-2)

for i in range(10):
    print(fibonacci(i))
"""

explanation = explain_code(code)
print(explanation)

5. Open WebUI 图形化界面基础安装

5.1 Open WebUI 介绍

Open WebUI（原名为 Ollama WebUI）是目前最受欢迎、功能最完善的 Ollama 图形化前端，它提供了类似 ChatGPT 的美观界面，让你无需使用命令行就能轻松使用本地大模型。

核心功能：

  • ✅ 完全开源免费，支持离线使用
  • ✅ 支持多模型切换，一键启动不同模型
  • ✅ 支持多轮对话、对话历史保存与管理
  • ✅ 支持多模态模型（图片识别）
  • ✅ 支持文件上传（PDF、TXT、Word 等）与文档问答
  • ✅ 支持自定义提示词模板
  • ✅ 支持代码高亮与复制
  • ✅ 支持暗黑模式与多种主题
  • ✅ 支持多用户管理

5.2 前置准备：安装 Docker Desktop

Open WebUI 官方强烈推荐使用 Docker 安装，这是最简单、最不容易出问题的方式。

系统要求
  • Windows 10 2004 及以上版本或 Windows 11
  • 必须启用 WSL 2（Windows Subsystem for Linux）
  • 至少 4GB 可用内存
详细安装步骤

  1. 下载 Docker Desktop

    • 访问 Docker 官网：https://www.docker.com/products/docker-desktop/
    • 点击 “Download for Windows” 按钮
    • 下载 Docker Desktop Installer.exe 安装包

  2. 安装 Docker Desktop

    • 双击下载的安装包
    • 在安装选项中，确保勾选 “Use WSL 2 instead of Hyper-V”（默认已勾选）
    • 点击 “OK” 开始安装
    • 等待安装完成（约 5-10 分钟）
    • 点击 “Close and restart” 重启电脑

  3. 验证安装

    • 重启电脑后，Docker Desktop 会自动启动
    • 等待 Docker 启动完成（系统托盘出现 Docker 图标且状态为 “Running”）
    • 打开终端（CMD/PowerShell），输入以下命令验证： 
      docker --version
    • 如果显示类似以下内容，说明安装成功： 
      Docker version 26.0.0, build 2ae903e

重要提示：如果安装过程中提示"WSL 2 installation is incomplete"，请按照提示下载并安装 WSL 2 Linux 内核更新包，然后重启电脑。

5.3 Docker 一键安装 Open WebUI

  1. 确保 Ollama 服务正在运行

    • 检查系统托盘是否有 Ollama 羊驼图标
    • 如果没有，手动启动 Ollama

  2. 配置 Ollama 允许本地 Docker 访问

    • 按下 Win + R，输入 sysdm.cpl，回车
    • 点击"高级" → “环境变量”
    • 在"系统变量"中点击"新建"
    • 变量名：OLLAMA_HOST
    • 变量值：0.0.0.0
    • 点击"确定"保存所有设置
    • 右键点击系统托盘的 Ollama 图标，选择 “Quit Ollama”
    • 重新从开始菜单启动 Ollama

  3. 执行 Docker 安装命令

    • 打开终端（CMD/PowerShell）
    • 复制并粘贴以下命令，回车执行： 
      docker run -d -p 3000:3000 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
    • 命令解释：
      • -d：后台运行容器
      • -p 3000:3000：将容器的 3000 端口映射到主机的 3000 端口
      • -v open-webui:/app/backend/data：创建数据卷，持久化保存聊天记录和配置
      • --name open-webui：给容器命名为 open-webui
      • --restart always：设置开机自启
      • ghcr.io/open-webui/open-webui:main：Open WebUI 最新镜像地址

  4. 等待安装完成

    • 第一次运行会自动下载 Open WebUI 镜像（约 2GB）
    • 下载速度取决于你的网络状况，通常需要 5-15 分钟
    • 可以在 Docker Desktop 的 “Containers” 页面查看安装进度

5.4 初始配置与登录

  1. 访问 Open WebUI

    • 打开任意浏览器（推荐 Chrome 或 Edge）
    • 在地址栏输入：http://localhost:3000
    • 你将看到 Open WebUI 的注册页面

  2. 创建管理员账户

    • 输入你的邮箱（可以是任意邮箱，仅用于本地登录）
    • 输入密码（至少 8 位）
    • 点击 “Sign Up” 按钮
    • 注册成功后会自动登录

  3. 连接 Ollama 服务

    • 登录后，Open WebUI 会自动检测并连接本地的 Ollama 服务
    • 如果连接成功，你会在页面左上角看到 “Connected to Ollama” 的提示
    • 如果没有自动连接，手动配置：
      1. 点击页面右上角的设置图标（⚙️）
      2. 在左侧菜单中选择 “Connections”
      3. 在 “Ollama” 部分，确认 API 地址为 http://host.docker.internal:11434
      4. 点击 “Save” 按钮
      5. 刷新页面

5.5 基本使用教程

1. 选择模型
  • 点击页面左上角的模型下拉菜单
  • 你会看到所有已经通过 ollama pull 下载到本地的模型
  • 点击你想要使用的模型即可切换
2. 开始对话
  • 在页面底部的输入框中输入你的问题
  • 点击发送按钮（➡️）或按回车键发送
  • 模型会实时生成回答，支持流式输出
  • 你可以随时点击停止按钮（⏹️）中断生成
3. 管理对话历史
  • 左侧边栏显示所有的对话历史
  • 点击任意对话可以继续之前的话题
  • 右键点击对话可以重命名、删除或导出
  • 点击顶部的 “New Chat” 按钮可以创建新的对话
4. 使用多模态模型（图片识别）
  • 首先下载一个多模态模型： 
    ollama pull llava:7b
  • 在 Open WebUI 中选择 llava:7b 模型
  • 点击输入框左侧的附件图标（📎）
  • 选择你想要识别的图片
  • 输入问题，例如：“描述一下这张图片”
  • 点击发送即可
5. 上传文件进行问答
  • 点击输入框左侧的附件图标（📎）
  • 选择你想要上传的文件（支持 PDF、TXT、Word、Excel 等格式）
  • 等待文件上传完成
  • 输入问题，例如：“总结一下这个文档的主要内容”
  • 模型会基于文件内容进行回答
6. 自定义提示词
  • 点击页面右上角的设置图标（⚙️）
  • 在左侧菜单中选择 “Prompts”
  • 点击 “Add Prompt” 按钮
  • 输入提示词名称和内容
  • 点击 “Save” 保存
  • 在对话中输入 / 即可快速选择并使用自定义提示词

5.6 常见问题与解决方案

问题 1：Open WebUI 无法连接到 Ollama

原因：Ollama 没有配置为允许 Docker 访问

解决方案：

  1. 确保已经按照 5.3 节的步骤设置了 OLLAMA_HOST=0.0.0.0 环境变量
  2. 重启 Ollama 服务
  3. 在 Open WebUI 的设置中，将 Ollama API 地址改为 http://host.docker.internal:11434
  4. 如果还是不行，尝试将 API 地址改为你的电脑局域网 IP 地址，例如 http://192.168.1.100:11434

问题 2：Docker 启动失败，提示 “WSL 2 is not installed”

解决方案：

  1. 打开 PowerShell（管理员模式）
  2. 输入以下命令安装 WSL 2： 
    wsl --install
  3. 等待安装完成，重启电脑
  4. 重新启动 Docker Desktop

问题 3：端口 3000 被占用

解决方案：

  1. 停止占用 3000 端口的程序
  2. 或者修改 Open WebUI 的映射端口，例如改为 8080： 
    docker stop open-webui
docker rm open-webui
docker run -d -p 8080:3000 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  3. 然后通过 http://localhost:8080 访问

问题 4：如何更新 Open WebUI 到最新版本

解决方案：

  1. 打开终端，执行以下命令： 
    docker stop open-webui
docker rm open-webui
docker pull ghcr.io/open-webui/open-webui:main
docker run -d -p 3000:3000 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  2. 你的聊天记录和配置会被保留，因为它们存储在数据卷中

问题 5：如何卸载 Open WebUI

解决方案：

  1. 打开终端，执行以下命令： 
    docker stop open-webui
docker rm open-webui
docker volume rm open-webui
  2. 这会删除 Open WebUI 容器和所有数据

6. Open WebUI 离线安装指南

适用场景：完全无网络环境、网络速度极慢、企业内网无法访问外网的情况。

6.1 离线安装准备工作

你需要准备一台有网络的电脑（称为"源电脑"），提前下载以下所有文件，然后通过U盘等存储设备转移到离线电脑上：

文件名称 下载地址 大小 说明
Docker Desktop 离线安装包 https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe ~600MB Docker 主程序
WSL 2 Linux 内核更新包 https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi ~15MB Windows 10/11 必需
Open WebUI Docker 镜像 需在源电脑上导出 ~2GB Open WebUI 主程序镜像
Ollama 离线安装包 https://ollama.com/download/windows ~100MB Ollama 主程序
至少一个 GGUF 格式模型 从 Hugging Face 等网站下载 4-6GB（7B模型） 例如 qwen2.5:7b-q4_K_M

6.2 步骤1：离线安装 Docker Desktop

  1. 安装 WSL 2 内核更新包

    • 双击运行下载的 wsl_update_x64.msi
    • 点击"Next" → “Finish” 完成安装
    • 重启电脑

  2. 安装 Docker Desktop

    • 双击运行 Docker Desktop Installer.exe
    • 确保勾选 “Use WSL 2 instead of Hyper-V”
    • 点击"OK"开始安装
    • 安装完成后点击"Close and restart"重启电脑
    • 重启后 Docker Desktop 会自动启动，等待其状态变为"Running"

  3. 验证 Docker 安装

    • 打开终端（CMD/PowerShell）
    • 输入 docker --version，显示版本信息即表示安装成功

6.3 步骤2：导出 Open WebUI Docker 镜像

在有网络的源电脑上执行以下操作：

  1. 确保源电脑已安装 Docker
  2. 拉取最新的 Open WebUI 镜像 
    docker pull ghcr.io/open-webui/open-webui:main
  3. 导出镜像为 tar 文件 
    docker save -o open-webui.tar ghcr.io/open-webui/open-webui:main
  4. 等待导出完成，你会在当前目录下得到一个约 2GB 的 open-webui.tar 文件
  5. 将此文件复制到 U 盘，准备转移到离线电脑

6.4 步骤3：离线导入并启动 Open WebUI

在离线电脑上执行以下操作：

  1. 将 U 盘中的 open-webui.tar 文件复制到离线电脑的任意目录
  2. 打开终端，进入该文件所在目录
  3. 导入 Docker 镜像 
    docker load -i open-webui.tar
  4. 等待导入完成，输入以下命令验证镜像是否存在： 
    docker images
    你应该能看到 ghcr.io/open-webui/open-webui 镜像
  5. 启动 Open WebUI 容器 
    docker run -d -p 3000:3000 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
  6. 等待容器启动完成（约 1-2 分钟）
  7. 访问 Open WebUI：打开浏览器，输入 http://localhost:3000

6.5 步骤4：离线导入 Ollama 模型

在有网络的源电脑上执行以下操作：

  1. 下载 GGUF 格式模型

    • 访问 Hugging Face：https://huggingface.co/
    • 搜索你需要的模型，例如 “qwen2.5 7b q4_K_M”
    • 下载后缀为 .gguf 的文件，例如 qwen2.5-7b-instruct-q4_k_m.gguf

  2. 创建 Modelfile

    • 在模型文件同一目录下创建一个名为 Modelfile 的文件（无后缀）
    • 内容如下： 
      FROM ./qwen2.5-7b-instruct-q4_k_m.gguf
TEMPLATE "{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"
PARAMETER stop "<|im_end|>"
PARAMETER stop "<|im_start|>"
    • 注意：不同模型的模板和停止词不同，请根据模型说明修改

在离线电脑上执行以下操作：

  1. 将模型文件和 Modelfile 复制到离线电脑的同一目录
  2. 打开终端，进入该目录
  3. 导入模型到 Ollama 
    ollama create qwen2.5:7b -f Modelfile
  4. 验证模型是否导入成功 
    ollama list
  5. 刷新 Open WebUI 页面，你应该能在模型列表中看到刚导入的模型

6.6 常见离线安装问题与解决方案

问题1：Docker 导入镜像失败，提示"no space left on device"

解决方案：

  • 清理 Docker 无用镜像和容器： 
    docker system prune -a
  • 更改 Docker 镜像存储位置到空间更大的磁盘

问题2：导入模型后 Open WebUI 看不到模型

解决方案：

  • 重启 Ollama 服务
  • 重启 Open WebUI 容器： 
    docker restart open-webui
  • 在 Open WebUI 设置中手动刷新模型列表

问题3：离线环境下无法使用嵌入模型（RAG功能异常）

解决方案：

  • 提前下载嵌入模型的 GGUF 版本
  • 在 Open WebUI 的 RAG 设置中手动指定本地嵌入模型

7. Open WebUI 高级功能教程

7.1 内置 RAG 知识库系统

RAG（检索增强生成）是 Open WebUI 最强大的功能之一，它允许你"喂"给模型自己的文档、数据和知识，让模型基于这些内容进行回答，突破模型训练数据的限制。

7.1.1 RAG 基本原理简介
用户提问 → 检索知识库中相关内容 → 将问题+相关内容一起发给大模型 → 模型基于知识库内容生成回答

优势：

  • ✅ 让模型了解最新信息和私有数据
  • ✅ 减少幻觉，提高回答准确性
  • ✅ 无需重新训练模型，成本极低
  • ✅ 完全本地运行，数据安全
7.1.2 快速使用：单文件临时问答

这是最简单的 RAG 使用方式，适合快速查询单个文件：

  1. 打开 Open WebUI 聊天界面
  2. 直接将文件拖入输入框，或点击输入框左侧的附件图标选择文件
    • 支持格式：PDF、DOCX、DOC、TXT、RTF、CSV、XLSX、PPTX、MD、HTML 等
  3. 等待文件上传和处理完成（系统会自动进行文本提取、分块和向量化）
  4. 输入问题，例如：“总结一下这个文档的主要内容”
  5. 模型会基于文件内容生成回答

注意：这种方式上传的文件只在当前对话中有效，关闭对话后会被删除。

7.1.3 创建和管理永久知识库

如果你需要多次使用同一批文档，建议创建永久知识库：

  1. 进入知识库管理界面

    • 点击左侧边栏的"工作空间"（Workspace）图标
    • 选择"知识库"（Knowledge Bases）选项
    • 点击右上角的"+ 创建知识库"按钮

  2. 配置知识库

    • 输入知识库名称（例如"公司技术文档"、“产品手册”）
    • 可选：输入知识库描述
    • 点击"创建"按钮

  3. 上传文档到知识库

    • 点击"添加文件"按钮
    • 选择你想要上传的多个文件
    • 等待文件处理完成（时间取决于文件大小和数量）
    • 你也可以添加网页链接，系统会自动爬取网页内容

  4. 使用知识库进行问答

    • 回到聊天主界面
    • 在输入框中输入 #，会弹出知识库选择菜单
    • 选择你想要使用的知识库
    • 输入问题并发送
    • 模型会自动检索知识库中的相关内容并生成回答
7.1.4 RAG 参数优化配置

合理配置 RAG 参数可以显著提高回答质量：

  1. 进入 RAG 设置界面

    • 点击右上角的设置图标（⚙️）
    • 在左侧菜单中选择"文档"（Documents）

  2. 关键参数说明

参数 默认值 推荐值 说明
分块大小（Chunk Size） 1000 500-2000 每个文本块的字符数。值越大，上下文越完整，但检索精度可能降低
分块重叠（Chunk Overlap） 100 100-200 相邻文本块之间的重叠字符数。防止信息在分块边界丢失
嵌入模型（Embedding Model） nomic-embed-text bge-m3 或 nomic-embed-text 用于将文本转换为向量的模型。bge-m3 中文效果更好
Top K 3 3-5 检索时返回的最相关文本块数量。值越大，信息越全面，但可能引入无关内容
相似度阈值 0.7 0.6-0.8 只返回相似度高于此值的文本块。值越高，检索越严格
  1. 中文优化建议
    • 将嵌入模型改为 bge-m3（需要先通过 ollama pull bge-m3 下载）
    • 分块大小设置为 800-1200
    • 分块重叠设置为 150-200
7.1.5 RAG 最佳实践与常见问题

最佳实践：

  • 优先使用结构化文档（如 Markdown、Word），避免扫描版 PDF
  • 大文档拆分为多个小文档上传
  • 给文档起清晰的文件名
  • 定期更新知识库内容

常见问题：

  • Q：模型回答不基于知识库内容
    A：提高相似度阈值，增加 Top K 值，检查文档是否正确处理
  • Q：回答中出现幻觉
    A：减小分块大小，增加分块重叠，使用更好的嵌入模型
  • Q：文档处理速度慢
    A：关闭其他占用资源的程序，使用更小的嵌入模型

7.2 插件与函数系统

Open WebUI 的插件与函数系统允许你扩展其功能，实现网页搜索、代码执行、数据查询等能力。

7.2.1 插件系统介绍

Open WebUI 支持两种类型的扩展：

  • 插件（Plugins）：功能更全面的扩展，通常有自己的界面
  • 函数（Functions）：轻量级扩展，主要用于在对话中调用特定功能

核心优势：

  • ✅ 一键安装和启用
  • ✅ 丰富的官方和社区插件
  • ✅ 支持自定义开发
  • ✅ 与对话系统无缝集成
7.2.2 安装官方插件/函数

  1. 进入插件管理界面

    • 点击右上角的设置图标（⚙️）
    • 在左侧菜单中选择"插件"（Plugins）或"函数"（Functions）

  2. 浏览并安装插件

    • 在"可用插件"列表中找到你想要安装的插件
    • 点击"安装"按钮
    • 等待安装完成

  3. 启用并配置插件

    • 安装完成后，插件会出现在"已安装插件"列表中
    • 打开插件右侧的开关启用它
    • 点击齿轮图标进入插件配置页面
    • 输入必要的 API 密钥或其他配置信息
    • 点击"保存"

  4. 使用插件

    • 回到聊天界面
    • 在输入框中输入 /，会弹出插件选择菜单
    • 选择你想要使用的插件
    • 按照提示输入必要的信息
    • 插件会自动执行并返回结果
7.2.3 常用插件推荐与使用

1. 网页搜索插件

  • 功能：让模型能够搜索互联网获取最新信息
  • 安装：在插件商店中搜索"Web Search"
  • 配置：无需 API 密钥，直接启用即可
  • 使用：在对话中输入 /web 搜索关键词，例如 /web 2026年最新科技新闻

2. 代码执行器插件

  • 功能：在安全的沙箱环境中执行 Python 代码
  • 安装：在插件商店中搜索"Code Interpreter"
  • 使用：在对话中输入 /code 然后粘贴你的 Python 代码
  • 示例： 
    /code
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2*np.pi, 100)
y = np.sin(x)

plt.plot(x, y)
plt.title('Sine Wave')
plt.show()

3. 保存输出插件

  • 功能：将模型的回答保存为本地文件
  • 安装：在函数商店中搜索"Save Outputs"
  • 使用：模型生成回答后，点击回答下方的"保存"按钮

4. 翻译插件

  • 功能：在对话中进行多语言翻译
  • 安装：在插件商店中搜索"Translate"
  • 使用：输入 /translate 目标语言 文本，例如 /translate 中文 Hello world
7.2.4 手动安装第三方插件

如果插件商店中没有你需要的插件，你可以手动安装第三方插件：

  1. 下载插件文件

    • 从 GitHub 等平台下载插件源代码
    • 通常是一个包含 plugin.py 和 README.md 的文件夹

  2. 将插件文件夹复制到 Open WebUI 插件目录

    • 打开 Docker Desktop
    • 进入 open-webui 容器的"Files"标签页
    • 导航到 /app/backend/data/plugins 目录
    • 将插件文件夹上传到此处

  3. 重启 Open WebUI 容器

    docker restart open-webui

  4. 启用并配置插件

    • 刷新 Open WebUI 页面
    • 进入插件管理界面，你应该能看到新安装的插件
    • 启用并配置插件

7.3 其他实用高级功能

7.3.1 多用户管理

Open WebUI 支持多用户管理，适合家庭或小团队使用：

  1. 进入管理员面板

    • 点击左下角的用户头像
    • 选择"管理员面板"（Admin Panel）

  2. 创建新用户

    • 点击"用户"（Users）选项
    • 点击"添加用户"按钮
    • 输入用户名、邮箱和密码
    • 选择用户角色（用户/管理员）
    • 点击"创建"

  3. 管理用户权限

    • 你可以禁用、删除用户或更改用户角色
    • 你可以限制用户可以使用的模型
    • 你可以查看用户的对话历史
7.3.2 自定义提示词库

你可以创建和保存常用的提示词模板，方便快速使用：

  1. 进入提示词管理界面

    • 点击左侧边栏的"提示词"（Prompts）图标
    • 点击"添加提示词"按钮

  2. 创建提示词模板

    • 输入提示词名称
    • 输入提示词内容
    • 可选：添加标签和描述
    • 点击"保存"

  3. 使用提示词模板

    • 在聊天输入框中输入 /
    • 选择你想要使用的提示词模板
    • 模板内容会自动填充到输入框中
    • 根据需要修改内容后发送
7.3.3 API 密钥管理

Open WebUI 提供了与 OpenAI 兼容的 API 接口，你可以生成 API 密钥供其他应用使用：

  1. 进入 API 密钥管理界面

    • 点击右上角的设置图标（⚙️）
    • 在左侧菜单中选择"API 密钥"（API Keys）

  2. 生成新的 API 密钥

    • 点击"生成新密钥"按钮
    • 输入密钥名称
    • 点击"生成"
    • 复制并保存生成的密钥（只会显示一次）

  3. 使用 API 密钥

    • 你可以在任何支持 OpenAI API 的应用中使用此密钥
    • API 基础地址：http://localhost:3000/v1
    • 示例： 
      from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="你的API密钥"
)

response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "你好"}]
)

print(response.choices[0].message.content)
7.3.4 主题与界面定制

Open WebUI 支持多种主题和界面定制选项：

  1. 切换主题

    • 点击右上角的设置图标（⚙️）
    • 在左侧菜单中选择"外观"（Appearance）
    • 选择你喜欢的主题（浅色、深色、自动）
    • 你还可以自定义主色调、字体等

  2. 自定义背景

    • 在"外观"设置中，你可以上传自定义背景图片
    • 你可以调整背景的模糊度和透明度

8. 进阶使用技巧

8.1 自定义模型参数

你可以通过创建 Modelfile 来自定义模型的参数，如上下文窗口大小、温度等。

示例：扩展上下文窗口

  1. 创建一个名为 Modelfile 的文件，内容如下：

    FROM qwen2.5:7b
PARAMETER num_ctx 32768  # 将上下文窗口扩展到 32K
PARAMETER temperature 0.5  # 设置温度为 0.5（更严谨）
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.1

  2. 创建自定义模型：

    ollama create qwen2.5:7b-32k -f Modelfile

  3. 运行自定义模型：

    ollama run qwen2.5:7b-32k

    或者在 Open WebUI 中选择该模型

8.2 远程访问配置

默认情况下，Ollama 和 Open WebUI 只允许本地访问。如果你想让其他设备（如手机、平板、其他电脑）访问你的服务，可以按照以下步骤配置：

配置 Ollama 远程访问
  1. 按下 Win + R，输入 sysdm.cpl，回车
  2. 点击"高级" → “环境变量”
  3. 在"系统变量"中点击"新建"
  4. 变量名：OLLAMA_HOST
  5. 变量值：0.0.0.0
  6. 点击"确定"保存所有设置
  7. 右键点击系统托盘的 Ollama 图标，选择 “Quit Ollama”
  8. 重新从开始菜单启动 Ollama
  9. 配置 Windows 防火墙允许 11434 端口入站连接
配置 Open WebUI 远程访问
  • Open WebUI 已经默认监听所有网络接口（0.0.0.0）
  • 只需要配置 Windows 防火墙允许 3000 端口入站连接
  • 在其他设备上，通过 http://你的电脑IP:3000 访问 Open WebUI

9. Open WebUI 与其他工具集成教程

Open WebUI 提供了与 OpenAI 完全兼容的 API 接口，这意味着几乎所有支持 OpenAI 的工具都可以无缝连接到你的本地大模型。下面介绍两个最常用的集成场景。

9.1 与 VS Code 集成：AI 编程助手

通过 Continue 扩展，你可以将本地大模型变成强大的 AI 编程助手，实现代码补全、代码解释、重构、调试等功能，完全免费且代码不会上传到云端。

9.1.1 安装 Continue 扩展
  1. 打开 VS Code
  2. 点击左侧边栏的"扩展"图标（或按 Ctrl+Shift+X）
  3. 在搜索框中输入 “Continue”
  4. 找到由 Continue Dev 开发的扩展，点击"安装"
  5. 安装完成后，VS Code 左侧会出现一个新的 Continue 图标
9.1.2 配置 Continue 连接 Open WebUI
  1. 点击左侧的 Continue 图标
  2. 在 Continue 侧边栏中，点击右上角的设置图标（⚙️）
  3. 选择"Open Config.json"，会打开 Continue 的配置文件
  4. 将配置文件内容替换为以下内容：
{
  "models": [
    {
      "title": "Open WebUI",
      "provider": "openai",
      "model": "qwen2.5:7b",
      "apiBase": "http://localhost:3000/v1",
      "apiKey": "你的Open WebUI API密钥",
      "contextLength": 32768
    }
  ],
  "tabAutocompleteModel": {
    "title": "Open WebUI",
    "provider": "openai",
    "model": "qwen2.5:1.8b",
    "apiBase": "http://localhost:3000/v1",
    "apiKey": "你的Open WebUI API密钥"
  },
  "embeddingsProvider": {
    "provider": "openai",
    "model": "bge-m3",
    "apiBase": "http://localhost:3000/v1",
    "apiKey": "你的Open WebUI API密钥"
  }
}

  1. 获取 Open WebUI API 密钥：

    • 打开 Open WebUI（http://localhost:3000）
    • 点击右上角的设置图标（⚙️）
    • 在左侧菜单中选择"API 密钥"
    • 点击"生成新密钥"，输入名称后点击"生成"
    • 复制生成的密钥，替换配置文件中的"你的Open WebUI API密钥"

  2. 保存配置文件（Ctrl+S）

  3. 重启 VS Code 使配置生效

9.1.3 基本使用方法

1. 代码解释与问答

  • 选中一段代码
  • 按 Ctrl+L 打开 Continue 聊天框
  • 输入问题，例如：“解释这段代码的功能”、“这段代码有什么问题”
  • 模型会基于选中的代码进行回答

2. 代码生成与补全

  • 在代码编辑器中输入注释，描述你想要实现的功能
  • 按 Ctrl+I 打开快速编辑框
  • 输入指令，例如：“实现一个快速排序算法”
  • 模型会直接在编辑器中生成代码

3. 代码重构

  • 选中需要重构的代码
  • 按 Ctrl+I
  • 输入指令，例如：“优化这段代码的性能”、“重命名变量使其更清晰”
  • 模型会生成重构后的代码，你可以选择接受或拒绝

4. 代码调试

  • 选中报错的代码
  • 按 Ctrl+L
  • 输入：“帮我调试这段代码，找出错误原因并修复”
  • 模型会分析错误并提供解决方案
9.1.4 常用快捷键
快捷键 功能
Ctrl+L 打开 Continue 聊天框
Ctrl+I 打开快速编辑框
Ctrl+Shift+R 重新生成回答
Ctrl+Shift+Y 接受代码建议
Ctrl+Shift+N 拒绝代码建议

9.2 与 Obsidian 集成：AI 笔记助手

通过 Text Generator 插件，你可以在 Obsidian 笔记中直接调用本地大模型，实现内容生成、总结、翻译、润色等功能，让你的笔记创作效率倍增。

9.2.1 安装 Text Generator 插件
  1. 打开 Obsidian
  2. 点击左下角的设置图标（⚙️）
  3. 在左侧菜单中选择"社区插件"
  4. 点击"关闭安全模式"
  5. 点击"浏览"按钮
  6. 在搜索框中输入 “Text Generator”
  7. 找到由 nhaouari 开发的插件，点击"安装"
  8. 安装完成后，点击"启用"按钮
9.2.2 配置 Text Generator 连接 Open WebUI

  1. 在 Text Generator 插件设置页面，找到"API 配置"部分

  2. 进行以下设置：

    • API 类型：选择 “OpenAI”
    • API 基础 URL：输入 http://localhost:3000/v1
    • API 密钥：输入你的 Open WebUI API 密钥（获取方法同上）
    • 模型：输入你想要使用的模型名称，例如 qwen2.5:7b
    • 最大令牌数：设置为 4096
    • 温度：设置为 0.7

  3. 点击"测试连接"按钮，确认连接成功

  4. 保存设置

9.2.3 基本使用方法

1. 快速生成内容

  • 在笔记中输入你的提示词
  • 选中提示词
  • 按 Ctrl+J（默认快捷键）
  • 模型会在提示词下方生成内容

2. 使用模板生成内容

  • Text Generator 提供了许多预设模板
  • 右键点击笔记编辑器
  • 选择"Text Generator" → “Templates”
  • 选择你想要使用的模板，例如：“总结文本”、“翻译文本”、“润色文本”
  • 按照提示输入内容即可

3. 创建自定义模板

  • 在 Text Generator 插件设置页面，找到"模板"部分
  • 点击"添加模板"按钮
  • 输入模板名称和提示词内容
  • 你可以使用变量 {{selectedText}} 来引用选中的文本
  • 示例模板： 
    请用简洁的语言总结以下文本：
{{selectedText}}
  • 保存模板后，就可以在右键菜单中使用了
9.2.4 实用场景示例
  • 笔记总结：选中长文本，使用"总结文本"模板生成摘要
  • 内容扩展：输入一个主题，让模型帮你扩展成完整的段落
  • 翻译：选中外文文本，使用"翻译文本"模板翻译成中文
  • 润色：选中你写的内容，使用"润色文本"模板优化语言表达
  • 头脑风暴：输入一个问题，让模型帮你生成多个想法

10. 不同硬件配置的模型推荐与性能优化指南

10.1 硬件配置分级标准

我们将 Windows 电脑的硬件配置分为四个等级，不同等级适合运行不同大小的模型：

等级 CPU 内存 显卡 适合模型大小
入门级 任意现代CPU 8GB 无或核显 0.5B-3B
进阶级 4核8线程及以上 16GB NVIDIA GTX 1650/RTX 2050及以上（4GB显存） 7B-14B
高端级 6核12线程及以上 32GB NVIDIA RTX 3060/4060及以上（8GB显存） 14B-34B
发烧级 8核16线程及以上 64GB+ NVIDIA RTX 3090/4090及以上（24GB显存） 70B+

10.2 各级别硬件最佳模型推荐

10.2.1 入门级配置（8GB内存，无独立显卡）

推荐模型：

  • Qwen 2.5:1.8B：中文能力最好的小模型，速度极快
  • Llama 3.2:1B：轻量高效，适合简单问答
  • Gemma 2:2B：Google出品，安全可靠

量化版本选择：q4_K_M（推荐）或 q3_K_M（更省内存）

性能表现：

  • 生成速度：20-40 tokens/秒
  • 适合任务：简单问答、文本补全、基础翻译
  • 不适合：复杂推理、代码生成、长文本处理
10.2.2 进阶级配置（16GB内存，4GB显存）

推荐模型：

  • Qwen 2.5:7B：综合性能最佳，中文能力强
  • Llama 3.2:7B：多语言支持好，推理能力强
  • DeepSeek R1:7B：数学和代码能力突出

量化版本选择：q4_K_M（推荐）或 q5_K_M（更好的质量）

性能表现：

  • 生成速度：30-60 tokens/秒（GPU加速）
  • 适合任务：日常问答、代码生成、文本总结、翻译
  • 不适合：超长文本处理、复杂数学推理
10.2.3 高端级配置（32GB内存，8GB显存）

推荐模型：

  • Qwen 2.5:14B：中文能力天花板，接近GPT-3.5水平
  • Llama 3.1:8B：综合性能强劲，多语言支持好
  • DeepSeek R1:14B：推理能力极强，适合复杂任务

量化版本选择：q4_K_M（推荐）或 q6_K（接近原生质量）

性能表现：

  • 生成速度：40-80 tokens/秒（GPU加速）
  • 适合任务：复杂推理、代码开发、长文本处理、文档问答
  • 可以流畅处理32K上下文窗口
10.2.4 发烧级配置（64GB+内存，24GB显存）

推荐模型：

  • Qwen 2.5:32B：开源中文模型的巅峰之作
  • Llama 3.1:70B：综合性能接近GPT-4
  • DeepSeek R1:34B：推理能力最强的开源模型之一

量化版本选择：q4_K_M（推荐）或 q8_0（原生质量）

性能表现：

  • 生成速度：30-50 tokens/秒（GPU加速）
  • 适合任务：专业级代码开发、复杂数学推理、大规模文档分析
  • 可以处理128K甚至更长的上下文窗口

10.3 Ollama 性能优化终极指南

10.3.1 模型选择优化

  1. 选择合适的量化版本

    • q2_K：极致压缩，质量损失较大，适合内存极度紧张的情况
    • q3_K_M：平衡压缩比和质量，推荐给8GB内存用户
    • q4_K_M：黄金标准，质量和速度的最佳平衡点，绝大多数用户的首选
    • q5_K_M：质量接近原生，推荐给16GB以上内存用户
    • q6_K：几乎无损，推荐给高端配置用户
    • q8_0：原生质量，只有发烧级配置推荐使用

  2. 优先选择针对中文优化的模型

    • 中文任务优先选择 Qwen、DeepSeek、通义千问等国产模型
    • 这些模型在中文理解和生成方面远优于国外模型
10.3.2 系统环境优化

  1. NVIDIA GPU 加速优化

    • 确保安装了最新的 NVIDIA 显卡驱动
    • Ollama 会自动检测并使用 CUDA 加速，无需额外配置
    • 验证 GPU 是否被使用：打开任务管理器 → 性能 → GPU，查看显存占用

  2. 内存优化

    • 关闭不必要的后台程序，释放内存
    • 增加虚拟内存大小（设置为物理内存的1.5-2倍）
    • 对于大模型，建议使用双通道内存

  3. 存储优化

    • 将模型存储在 SSD 上，加载速度会比 HDD 快很多
    • 定期清理不需要的模型，释放磁盘空间
10.3.3 Ollama 参数优化

  1. 调整并行处理参数

    • 创建或编辑 Modelfile，添加以下参数： 
      PARAMETER num_thread 8  # 设置为你的CPU核心数
PARAMETER num_gpu 1    # 使用1个GPU（如果有多个GPU可以增加）

  2. 调整上下文窗口大小

    • 只在需要时使用大上下文窗口
    • 上下文窗口越大，内存占用越高，速度越慢
    • 示例： 
      PARAMETER num_ctx 8192  # 对于大多数任务，8K已经足够

  3. 调整生成参数

    • 降低 temperature 可以提高生成速度和稳定性
    • 降低 top_k 和 top_p 可以减少计算量
    • 示例： 
      PARAMETER temperature 0.5
PARAMETER top_k 40
PARAMETER top_p 0.9
10.3.4 常见性能问题解决方案

问题1：模型加载速度慢

  • 解决方案：将模型存储在 SSD 上；使用更小的量化版本；增加内存

问题2：生成速度慢

  • 解决方案：确保 GPU 加速正常工作；使用更小的模型；降低量化等级；调整 num_thread 参数

问题3：运行模型时电脑卡顿

  • 解决方案：关闭其他占用资源的程序；使用更小的模型；增加虚拟内存

问题4：显存不足

  • 解决方案：使用更低量化等级的模型；减小上下文窗口大小；关闭其他使用显存的程序

11. Ollama 模型离线下载与国内镜像源

11.1 为什么需要国内镜像源

Ollama 官方服务器位于国外，国内用户直接下载模型时经常会遇到以下问题：

  • 下载速度极慢（通常只有几十 KB/s）
  • 下载过程中频繁中断
  • 大模型（如 70B 级）几乎无法下载完成

使用国内镜像源可以将下载速度提升至 MB/s 甚至几十 MB/s，大幅节省时间。

11.2 2026 年最新可用国内镜像源列表

镜像源名称 地址 状态 备注
飞书镜像 https://ollama.fly.dev ✅ 可用 速度快，稳定性好，推荐首选
阿里云镜像 https://ollama.aliyuncs.com ✅ 可用 官方合作镜像，速度极快
腾讯云镜像 https://ollama.tencentcloudcr.com ✅ 可用 南方用户推荐
华为云镜像 https://ollama.huaweicloud.com ✅ 可用 北方用户推荐
南京大学镜像 https://mirrors.nju.edu.cn/ollama ✅ 可用 教育网用户推荐

11.3 临时使用镜像源的方法

如果你只是想临时使用镜像源下载某个模型，可以在终端中执行以下命令：

Windows CMD：

set OLLAMA_HOST=https://ollama.fly.dev
ollama pull qwen2.5:7b

Windows PowerShell：

$env:OLLAMA_HOST = "https://ollama.fly.dev"
ollama pull qwen2.5:7b

注意：这种方法只对当前终端会话有效，关闭终端后会恢复为官方源。

11.4 永久配置镜像源的方法

如果你想永久使用国内镜像源，可以按照以下步骤配置：

  1. 按下 Win + R，输入 sysdm.cpl，回车
  2. 点击"高级" → “环境变量”
  3. 在"系统变量"中点击"新建"
  4. 变量名：OLLAMA_HOST
  5. 变量值：https://ollama.fly.dev（选择上表中任意一个镜像源）
  6. 点击"确定"保存所有设置
  7. 右键点击系统托盘的 Ollama 图标，选择 “Quit Ollama”
  8. 重新从开始菜单启动 Ollama

验证配置是否生效：
打开终端，输入以下命令：

ollama pull qwen2.5:7b

如果下载速度明显提升，说明配置成功。

11.5 手动下载 GGUF 模型的详细步骤

如果镜像源也无法满足你的需求，或者你需要下载一些不在 Ollama 官方库中的模型，可以手动下载 GGUF 格式的模型文件，然后导入到 Ollama 中。

步骤1：找到并下载 GGUF 模型文件
  1. 访问 Hugging Face 网站：https://huggingface.co/
  2. 在搜索框中输入你想要的模型名称 + “GGUF”，例如 “qwen2.5 7b GGUF”
  3. 在搜索结果中，选择由官方或知名开发者发布的模型
  4. 进入模型页面后，点击"Files and versions"标签
  5. 找到你需要的量化版本文件，例如 qwen2.5-7b-instruct-q4_k_m.gguf
  6. 点击文件名右侧的下载图标进行下载

推荐下载的量化版本：q4_K_M（绝大多数用户的首选）

步骤2：创建 Modelfile

在下载的 GGUF 文件同一目录下，创建一个名为 Modelfile 的文件（无后缀名）。

注意：不同模型的 Modelfile 内容不同，必须使用正确的模板和停止词，否则模型会出现回答异常、重复输出等问题。

常用模型 Modelfile 模板：

Qwen 2.5 系列：

FROM ./qwen2.5-7b-instruct-q4_k_m.gguf
TEMPLATE "{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"
PARAMETER stop "<|im_end|>"
PARAMETER stop "<|im_start|>"
PARAMETER num_ctx 32768

Llama 3.2 系列：

FROM ./llama-3.2-7b-instruct-q4_k_m.gguf
TEMPLATE "{{ if .System }}<|start_header_id|>system<|end_header_id|>

{{ .System }}<|eot_id|>{{ end }}{{ if .Prompt }}<|start_header_id|>user<|end_header_id|>

{{ .Prompt }}<|eot_id|>{{ end }}<|start_header_id|>assistant<|end_header_id|>

"
PARAMETER stop "<|eot_id|>"
PARAMETER stop "<|start_header_id|>"
PARAMETER stop "<|end_header_id|>"
PARAMETER num_ctx 131072

DeepSeek R1 系列：

FROM ./deepseek-r1-7b-chat-q4_k_m.gguf
TEMPLATE "{{ if .System }}<|begin_of_solution|>{{ .System }}<|end_of_solution|>{{ end }}{{ if .Prompt }}<|begin_of_thought|>{{ .Prompt }}<|end_of_thought|>{{ end }}<|begin_of_answer|>"
PARAMETER stop "<|end_of_answer|>"
PARAMETER stop "<|begin_of_thought|>"
PARAMETER stop "<|end_of_thought|>"
PARAMETER num_ctx 128000
步骤3：导入模型到 Ollama

  1. 打开终端，进入 GGUF 文件和 Modelfile 所在的目录

  2. 执行以下命令导入模型：

    ollama create qwen2.5:7b-custom -f Modelfile

    其中 qwen2.5:7b-custom 是你给这个模型起的名字，可以任意修改

  3. 验证模型是否导入成功：

    ollama list

    你应该能看到刚导入的模型

  4. 测试模型：

    ollama run qwen2.5:7b-custom
>>> 你好

11.6 批量下载多个模型

如果你需要一次性下载多个模型，可以创建一个批处理脚本：

  1. 创建一个名为 download_models.bat 的文件

  2. 内容如下：

    @echo off
set OLLAMA_HOST=https://ollama.fly.dev

echo 开始下载模型...

ollama pull qwen2.5:1.8b
ollama pull qwen2.5:7b
ollama pull llava:7b
ollama pull bge-m3

echo 所有模型下载完成！
pause

  3. 双击运行这个批处理文件，它会自动依次下载所有指定的模型

11.7 常见下载问题与解决方案

问题1：下载过程中中断，重新下载会从头开始吗？

答案：不会。Ollama 支持断点续传，重新执行 ollama pull 命令会从中断的地方继续下载。

问题2：提示"manifest unknown"错误

原因：模型名称或版本号错误

解决方案：

  • 检查模型名称是否正确
  • 访问 Ollama 模型库（https://ollama.com/library）确认正确的模型名称和标签

问题3：提示"context deadline exceeded"错误

原因：网络连接超时

解决方案：

  • 更换其他镜像源
  • 检查网络连接是否正常
  • 尝试使用代理

问题4：下载的模型无法在 Open WebUI 中看到

解决方案：

  • 重启 Ollama 服务
  • 重启 Open WebUI 容器： 
    docker restart open-webui
  • 在 Open WebUI 设置中手动刷新模型列表

12. Open WebUI 自定义插件开发入门

Open WebUI 提供了强大的插件系统，允许你使用 Python 开发自定义插件，扩展其功能。本节将带你从零开始开发你的第一个 Open WebUI 插件。

12.1 插件开发环境准备

必备工具：

  • Python 3.10 及以上版本
  • 文本编辑器或 IDE（推荐 VS Code）
  • 已安装并运行的 Open WebUI

安装开发依赖：

pip install open-webui

12.2 插件的基本结构

一个标准的 Open WebUI 插件包含以下文件：

my_plugin/
├── __init__.py       # 插件入口文件
├── plugin.py         # 插件主逻辑
├── config.json       # 插件配置文件
└── README.md         # 插件说明文档

核心文件说明：

  1. config.json：包含插件的基本信息，如名称、版本、描述等

    {
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "这是我的第一个 Open WebUI 插件",
  "author": "你的名字",
  "url": "https://github.com/你的用户名/你的仓库"
}

  2. plugin.py：插件的主逻辑文件，包含插件的所有功能实现

    from open_webui import Plugin

class MyPlugin(Plugin):
    def __init__(self):
        super().__init__()
        # 插件初始化代码
    
    def run(self, params):
        # 插件执行代码
        return "Hello from My Plugin!"

# 导出插件类
plugin = MyPlugin()

12.3 第一个插件：Hello World

让我们创建一个最简单的"Hello World"插件，当用户输入 /hello 时，插件会返回"Hello, World!"。

步骤1：创建插件目录和文件
  1. 在任意位置创建一个名为 hello_world 的文件夹
  2. 在文件夹中创建以下三个文件：

config.json：

{
  "name": "Hello World",
  "version": "1.0.0",
  "description": "一个简单的 Hello World 插件",
  "author": "你的名字",
  "url": ""
}

plugin.py：

from open_webui import Plugin

class HelloWorldPlugin(Plugin):
    def __init__(self):
        super().__init__()
        # 注册命令
        self.register_command("hello", self.hello_command)
    
    def hello_command(self, params):
        """
        向用户问好
        使用方法: /hello [名字]
        """
        if params:
            name = params.strip()
            return f"你好，{name}！"
        else:
            return "你好，世界！"

# 导出插件类
plugin = HelloWorldPlugin()

README.md：

# Hello World 插件

这是一个简单的 Open WebUI 插件，用于演示插件开发的基本流程。

## 使用方法

在聊天输入框中输入：
- `/hello`：返回"你好，世界！"
- `/hello 张三`：返回"你好，张三！"
步骤2：安装插件
  1. 打开 Docker Desktop
  2. 进入 open-webui 容器的"Files"标签页
  3. 导航到 /app/backend/data/plugins 目录
  4. 将整个 hello_world 文件夹上传到此处
  5. 重启 Open WebUI 容器： 
    docker restart open-webui
步骤3：测试插件
  1. 打开 Open WebUI（http://localhost:3000）
  2. 在聊天输入框中输入 /，你应该能看到 hello 命令
  3. 输入 /hello 并发送，插件会返回"你好，世界！"
  4. 输入 /hello 张三 并发送，插件会返回"你好，张三！"

恭喜你！你已经成功开发并安装了你的第一个 Open WebUI 插件。

12.4 插件核心 API 介绍

Open WebUI 插件系统提供了丰富的 API，让你可以实现各种功能。以下是最常用的几个 API：

1. 注册命令
self.register_command(name, handler, description=None)
  • name：命令名称，用户通过 /name 调用
  • handler：命令处理函数
  • description：命令描述，会显示在命令列表中
2. 获取用户信息
self.get_user()

返回当前登录用户的信息，包括 id、name、email 等。

3. 发送消息
self.send_message(content, role="assistant")
  • content：消息内容
  • role：消息角色，可以是 “user”、“assistant” 或 “system”
4. 调用大模型
self.call_model(model, messages, stream=False)
  • model：模型名称
  • messages：消息列表，格式为 [{"role": "user", "content": "你好"}]
  • stream：是否流式输出
5. 获取配置
self.get_config(key, default=None)

获取插件的配置值。

6. 设置配置
self.set_config(key, value)

设置插件的配置值。

12.5 实用插件示例：随机名言生成器

让我们开发一个更实用的插件：随机名言生成器。当用户输入 /quote 时，插件会返回一条随机的名人名言。

步骤1：创建插件文件

创建一个名为 random_quote 的文件夹，包含以下文件：

config.json：

{
  "name": "随机名言生成器",
  "version": "1.0.0",
  "description": "生成随机的名人名言",
  "author": "你的名字",
  "url": ""
}

plugin.py：

from open_webui import Plugin
import random

class RandomQuotePlugin(Plugin):
    def __init__(self):
        super().__init__()
        self.register_command("quote", self.quote_command, "生成一条随机的名人名言")
        
        # 名言数据库
        self.quotes = [
            {"text": "生活不是等待风暴过去，而是学会在雨中跳舞。", "author": "维维安·格林"},
            {"text": "成功不是终点，失败也不是致命的，重要的是继续前进的勇气。", "author": "温斯顿·丘吉尔"},
            {"text": "你的时间有限，不要浪费在过别人的生活上。", "author": "史蒂夫·乔布斯"},
            {"text": "千里之行，始于足下。", "author": "老子"},
            {"text": "学而不思则罔，思而不学则殆。", "author": "孔子"},
            {"text": "天行健，君子以自强不息。", "author": "周易"},
            {"text": "不积跬步，无以至千里；不积小流，无以成江海。", "author": "荀子"},
            {"text": "业精于勤，荒于嬉；行成于思，毁于随。", "author": "韩愈"}
        ]
    
    def quote_command(self, params):
        """
        生成一条随机的名人名言
        使用方法: /quote
        """
        quote = random.choice(self.quotes)
        return f"**{quote['text']}**\n\n—— {quote['author']}"

# 导出插件类
plugin = RandomQuotePlugin()

README.md：

# 随机名言生成器插件

一个简单的 Open WebUI 插件，用于生成随机的名人名言。

## 使用方法

在聊天输入框中输入：
- `/quote`：生成一条随机的名人名言
步骤2：安装和测试插件

按照 12.3 节的步骤安装插件，然后在 Open WebUI 中输入 /quote 测试。

12.6 插件的打包与安装

如果你想分享你的插件给其他人使用，可以将插件打包成 ZIP 文件：

  1. 将插件文件夹（如 random_quote）压缩成 ZIP 文件
  2. 分享这个 ZIP 文件给其他人
  3. 其他人可以通过以下方式安装：
    • 打开 Open WebUI
    • 进入设置 → 插件
    • 点击"上传插件"按钮
    • 选择 ZIP 文件进行上传

12.7 插件开发最佳实践与资源

最佳实践：

  1. 保持插件功能单一，一个插件只做一件事
  2. 提供清晰的使用说明和示例
  3. 处理可能的异常情况
  4. 遵循 Python 编码规范
  5. 定期更新插件以兼容最新版本的 Open WebUI

推荐资源：

  • Open WebUI 插件开发文档：https://docs.openwebui.com/developers/plugins
  • Open WebUI 官方插件示例：https://github.com/open-webui/plugins
  • Open WebUI 社区插件商店：https://openwebui.com/plugins

13. Ollama REST API 完整参考文档

Ollama 提供了一套完整的 REST API 接口，允许开发者将本地大模型集成到自己的应用程序中。所有接口都使用 JSON 格式进行数据交换，支持流式输出。

13.1 API 基础信息

  • 基础地址：http://localhost:11434/api
  • 请求方法：所有接口均使用 POST 方法
  • Content-Type：application/json
  • 认证：默认不需要认证（生产环境建议配置）

13.2 生成文本接口

用于生成文本补全，适合单轮问答和文本生成任务。

接口地址：POST /api/generate

请求参数：

参数名 类型 必填 默认值 说明
model string 是 - 模型名称，如 “qwen2.5:7b”
prompt string 是 - 输入提示词
system string 否 - 系统提示词
template string 否 - 自定义提示词模板
context array 否 - 上一次对话的上下文，用于多轮对话
stream boolean 否 true 是否流式输出
raw boolean 否 false 是否不应用模型模板
format string 否 - 输出格式，支持 “json”
options object 否 - 模型参数，如 temperature、top_p 等

响应参数：

参数名 类型 说明
model string 模型名称
created_at string 创建时间
response string 生成的文本（流式输出时逐 token 返回）
done boolean 是否生成完成
context array 对话上下文，可用于下一次请求
total_duration number 总耗时（纳秒）
load_duration number 模型加载耗时（纳秒）
prompt_eval_count number 提示词 token 数
prompt_eval_duration number 提示词评估耗时（纳秒）
eval_count number 生成 token 数
eval_duration number 生成耗时（纳秒）

示例 1：非流式输出

import requests
import json

url = "http://localhost:11434/api/generate"
payload = {
    "model": "qwen2.5:7b",
    "prompt": "用一句话介绍人工智能",
    "stream": False
}

response = requests.post(url, json=payload)
result = response.json()

print(result["response"])

示例 2：流式输出

import requests
import json

url = "http://localhost:11434/api/generate"
payload = {
    "model": "qwen2.5:7b",
    "prompt": "写一个关于春天的短诗",
    "stream": True
}

response = requests.post(url, json=payload, stream=True)

for line in response.iter_lines():
    if line:
        data = json.loads(line)
        print(data.get("response", ""), end="", flush=True)

print()

示例 3：JSON 格式输出

import requests
import json

url = "http://localhost:11434/api/generate"
payload = {
    "model": "qwen2.5:7b",
    "prompt": "生成一个包含姓名、年龄、职业的用户信息",
    "format": "json",
    "stream": False
}

response = requests.post(url, json=payload)
result = response.json()

user_info = json.loads(result["response"])
print(user_info)

13.3 聊天接口

用于多轮对话，支持系统提示词和消息历史。

接口地址：POST /api/chat

请求参数：

参数名 类型 必填 默认值 说明
model string 是 - 模型名称
messages array 是 - 消息列表
stream boolean 否 true 是否流式输出
format string 否 - 输出格式，支持 “json”
options object 否 - 模型参数

消息对象结构：

参数名 类型 说明
role string 角色，可选值：“system”、“user”、“assistant”
content string 消息内容
images array 图片列表（base64 编码），用于多模态模型

响应参数：

参数名 类型 说明
model string 模型名称
created_at string 创建时间
message object 生成的消息对象
done boolean 是否生成完成
total_duration number 总耗时（纳秒）
load_duration number 模型加载耗时（纳秒）
prompt_eval_count number 提示词 token 数
prompt_eval_duration number 提示词评估耗时（纳秒）
eval_count number 生成 token 数
eval_duration number 生成耗时（纳秒）

示例：多轮对话

import requests
import json

url = "http://localhost:11434/api/chat"
messages = [
    {"role": "system", "content": "你是一个乐于助人的助手。"},
    {"role": "user", "content": "你好，我叫张三。"}
]

payload = {
    "model": "qwen2.5:7b",
    "messages": messages,
    "stream": False
}

response = requests.post(url, json=payload)
result = response.json()

assistant_message = result["message"]
print(assistant_message["content"])

# 添加助手回复到消息历史
messages.append(assistant_message)

# 继续对话
messages.append({"role": "user", "content": "我叫什么名字？"})

payload["messages"] = messages
response = requests.post(url, json=payload)
result = response.json()

print(result["message"]["content"])

13.4 模型管理接口

13.4.1 获取本地模型列表

接口地址：GET /api/tags

响应示例：

{
  "models": [
    {
      "name": "qwen2.5:7b",
      "id": "78e26419910c",
      "size": 4700000000,
      "digest": "sha256:78e26419910c...",
      "modified_at": "2026-04-09T10:00:00Z"
    }
  ]
}
13.4.2 查看模型详情

接口地址：POST /api/show

请求参数：

{
  "name": "qwen2.5:7b"
}

响应示例：

{
  "modelfile": "# Modelfile generated by Ollama\nFROM qwen2.5:7b\n...",
  "parameters": "PARAMETER temperature 0.7\n...",
  "template": "{{ if .System }}<|im_start|>system\n...",
  "details": {
    "parent_model": "",
    "format": "gguf",
    "family": "qwen2",
    "families": ["qwen2"],
    "parameter_size": "7B",
    "quantization_level": "Q4_K_M"
  }
}
13.4.3 创建模型

接口地址：POST /api/create

请求参数：

{
  "name": "qwen2.5:7b-custom",
  "modelfile": "FROM qwen2.5:7b\nPARAMETER temperature 0.5"
}
13.4.4 删除模型

接口地址：DELETE /api/delete

请求参数：

{
  "name": "qwen2.5:7b-custom"
}
13.4.5 拉取模型

接口地址：POST /api/pull

请求参数：

{
  "name": "llava:7b",
  "stream": false
}

13.5 嵌入接口

用于将文本转换为向量表示，常用于 RAG 知识库和语义搜索。

接口地址：POST /api/embeddings

请求参数：

参数名 类型 必填 默认值 说明
model string 是 - 嵌入模型名称，如 “bge-m3”
prompt string 是 - 输入文本
options object 否 - 模型参数

响应参数：

参数名 类型 说明
embedding array 向量表示

示例：

import requests
import json

url = "http://localhost:11434/api/embeddings"
payload = {
    "model": "bge-m3",
    "prompt": "人工智能是未来的发展方向"
}

response = requests.post(url, json=payload)
result = response.json()

embedding = result["embedding"]
print(f"向量维度: {len(embedding)}")
print(f"前5个值: {embedding[:5]}")

13.6 其他实用接口

13.6.1 检查服务状态

接口地址：GET /

响应：Ollama is running

13.6.2 查看运行中的模型

接口地址：GET /api/ps

响应示例：

{
  "models": [
    {
      "name": "qwen2.5:7b",
      "id": "78e26419910c",
      "size": 4700000000,
      "digest": "sha256:78e26419910c...",
      "expires_at": "2026-04-09T11:00:00Z"
    }
  ]
}

14. 基于 Ollama 和 Open WebUI 搭建企业内部 AI 助手

Ollama 配合 Open WebUI 是搭建企业内部 AI 助手的理想选择，它具有隐私安全、成本低廉、部署简单、功能丰富等优势。

14.1 企业部署的优势与考虑因素

企业部署优势：

  • ✅ 数据安全：所有数据在企业内部处理，不会泄露到外部
  • ✅ 成本可控：一次性硬件投入，无后续订阅费用
  • ✅ 定制化强：可以根据企业需求定制模型和功能
  • ✅ 离线可用：无需依赖外部网络
  • ✅ 易于集成：可以与企业现有系统无缝集成

需要考虑的因素：

  • 硬件成本与性能平衡
  • 网络安全与访问控制
  • 多用户并发访问能力
  • 模型更新与维护
  • 知识库建设与管理

14.2 硬件配置与服务器选型

根据企业规模和使用人数，推荐以下硬件配置：

企业规模 同时在线人数 推荐服务器配置 支持模型大小
小型团队（10人以下） 2-5人 CPU：8核16线程
内存：32GB
显卡：RTX 4060 Ti（8GB）
存储：512GB SSD		 7B-14B
中型团队（10-50人） 5-20人 CPU：16核32线程
内存：64GB
显卡：RTX 4080（16GB）
存储：1TB SSD		 14B-34B
大型团队（50-200人） 20-50人 CPU：32核64线程
内存：128GB
显卡：RTX 4090（24GB）×2
存储：2TB SSD		 34B-70B
企业级（200人以上） 50人以上 多台服务器集群
每台配置：
CPU：32核64线程
内存：128GB
显卡：RTX 4090（24GB）×2
存储：2TB SSD		 70B+

服务器选型建议：

  • 优先选择 NVIDIA 显卡，CUDA 加速效果最好
  • 内存至少是显存的 2 倍
  • 必须使用 SSD 存储，模型加载速度会快很多
  • 对于大型企业，建议使用服务器级显卡（如 A10、A100）

14.3 网络架构与安全设计

14.3.1 推荐网络架构
企业内网
    |
    ├── 防火墙
    |       |
    |       ├── Open WebUI 服务器（端口 3000）
    |       |       |
    |       |       └── Ollama 服务器（端口 11434）
    |       |
    |       └── 其他企业系统
    |
    └── 员工电脑

最佳实践：

  • 将 Ollama 和 Open WebUI 部署在同一台服务器上
  • 只开放 Open WebUI 的 3000 端口给企业内网
  • 不将任何端口暴露到公网
  • 使用 HTTPS 加密通信
14.3.2 安全配置

  1. 启用 HTTPS

    • 生成自签名证书或使用企业内部 CA 颁发的证书
    • 修改 Open WebUI 启动命令，启用 HTTPS： 
      docker run -d -p 3000:3000 -p 3001:3001 \
  -v open-webui:/app/backend/data \
  -v /path/to/certs:/app/backend/certs \
  -e ENABLE_HTTPS=true \
  -e HTTPS_CERT_FILE=/app/backend/certs/cert.pem \
  -e HTTPS_KEY_FILE=/app/backend/certs/key.pem \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

  2. 配置访问控制

    • 禁用用户注册功能，由管理员统一创建用户
    • 修改 Open WebUI 启动命令，添加以下环境变量： 
      -e ENABLE_SIGNUP=false

  3. 设置密码策略

    • 要求用户使用强密码
    • 定期强制用户更改密码

  4. 日志审计

    • 启用 Open WebUI 的日志功能
    • 定期审查用户操作日志
    • 记录所有模型调用请求

14.4 多用户与权限管理

Open WebUI 提供了完善的多用户和权限管理功能，适合企业使用。

14.4.1 用户角色与权限

Open WebUI 支持三种用户角色：

角色 权限
用户 可以使用模型、创建对话、管理自己的知识库
管理员 拥有用户的所有权限，还可以管理用户、模型、系统设置
超级管理员 拥有管理员的所有权限，还可以管理其他管理员
14.4.2 用户管理操作

  1. 创建用户

    • 使用管理员账户登录 Open WebUI
    • 点击左下角的用户头像 → 管理员面板 → 用户
    • 点击"添加用户"按钮
    • 输入用户名、邮箱、密码
    • 选择用户角色
    • 点击"创建"

  2. 限制用户可用模型

    • 在用户管理页面，点击用户右侧的"编辑"按钮
    • 在"模型访问"部分，选择该用户可以使用的模型
    • 点击"保存"

  3. 禁用用户

    • 在用户管理页面，点击用户右侧的"禁用"按钮
    • 被禁用的用户将无法登录系统

14.5 企业知识库建设

RAG 知识库是企业内部 AI 助手的核心功能，它可以让 AI 助手了解企业的内部知识和业务流程。

14.5.1 知识库建设流程

  1. 知识收集

    • 收集企业内部的文档、手册、规范、FAQ 等
    • 将纸质文档转换为电子文档
    • 整理和分类知识内容

  2. 知识预处理

    • 去除文档中的无关内容
    • 将大文档拆分为小文档
    • 统一文档格式（推荐使用 Markdown）

  3. 知识库创建

    • 在 Open WebUI 中创建知识库
    • 上传预处理后的文档
    • 等待文档处理完成

  4. 知识库测试与优化

    • 测试知识库的问答效果
    • 根据测试结果调整 RAG 参数
    • 不断补充和更新知识库内容
14.5.2 企业知识库最佳实践
  • 分部门创建知识库：每个部门创建自己的知识库，只允许本部门员工访问
  • 定期更新知识库：指定专人负责知识库的维护和更新
  • 建立审核机制：所有上传到知识库的内容都需要经过审核
  • 使用高质量的嵌入模型：推荐使用 bge-m3 或 gte-large 嵌入模型
  • 优化文档结构：使用清晰的标题和段落结构，便于模型理解

14.6 监控与维护

为了确保企业内部 AI 助手的稳定运行，需要建立完善的监控和维护机制。

14.6.1 系统监控

  1. 硬件资源监控

    • 监控 CPU、内存、显存、磁盘使用率
    • 设置资源告警阈值
    • 推荐使用 Prometheus + Grafana 进行监控

  2. 服务状态监控

    • 监控 Ollama 和 Open WebUI 服务状态
    • 服务异常时自动发送告警
    • 配置服务自动重启

  3. 性能监控

    • 监控模型响应时间
    • 监控并发用户数
    • 监控模型调用次数
14.6.2 日常维护

  1. 定期更新

    • 定期更新 Ollama 和 Open WebUI 到最新版本
    • 定期更新模型到最新版本
    • 定期更新系统和依赖包

  2. 数据清理

    • 定期清理无用的对话历史
    • 定期清理临时文件
    • 定期清理日志文件

  3. 性能优化

    • 根据使用情况调整模型参数
    • 根据使用情况调整服务器配置
    • 定期进行性能测试

14.7 备份与恢复

数据备份是企业部署中非常重要的一环，需要建立完善的备份和恢复机制。

14.7.1 需要备份的数据

  1. Open WebUI 数据

    • 用户信息
    • 对话历史
    • 知识库内容
    • 系统配置
    • 插件和函数

  2. Ollama 数据

    • 模型文件
    • 模型配置
14.7.2 备份方法

  1. 备份 Open WebUI 数据

    docker run --rm -v open-webui:/app/backend/data -v /path/to/backup:/backup alpine tar czf /backup/open-webui-backup-$(date +%Y%m%d).tar.gz -C /app/backend/data .

  2. 备份 Ollama 数据

    • Windows：备份 C:\Users\用户名\.ollama\models 目录
    • Linux：备份 /usr/share/ollama/.ollama/models 目录
14.7.3 恢复方法

  1. 恢复 Open WebUI 数据

    docker stop open-webui
docker run --rm -v open-webui:/app/backend/data -v /path/to/backup:/backup alpine sh -c "rm -rf /app/backend/data/* && tar xzf /backup/open-webui-backup-20260409.tar.gz -C /app/backend/data"
docker start open-webui

  2. 恢复 Ollama 数据

    • 将备份的模型文件复制到 Ollama 模型目录
    • 重启 Ollama 服务

14.8 部署最佳实践

  1. 使用 Docker Compose 部署

    • 创建 docker-compose.yml 文件： 
      version: '3'
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    volumes:
      - ollama:/root/.ollama
    ports:
      - "11434:11434"
    restart: always
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
  
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    volumes:
      - open-webui:/app/backend/data
    ports:
      - "3000:3000"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - ENABLE_SIGNUP=false
    restart: always
    depends_on:
      - ollama

volumes:
  ollama:
  open-webui:
    • 启动服务： 
      docker-compose up -d

  2. 负载均衡与高可用

    • 对于大型企业，建议部署多个 Ollama 实例
    • 使用 Nginx 进行负载均衡
    • 配置主从复制，实现高可用

  3. 模型预热

    • 在系统启动时自动加载常用模型
    • 避免用户首次使用时等待模型加载

  4. 使用专用服务器

    • 将 AI 服务部署在专用服务器上
    • 不要与其他业务系统共享服务器资源

15. 常见问题汇总

Q1：Ollama 支持多模态模型吗？
A1：是的，Ollama 现在支持一些多模态模型，如 Llama 3.2 Vision、Qwen-VL、LLaVA 等。你可以使用 ollama pull llava 来运行多模态模型。

Q2：如何查看 Ollama 占用了多少显存？
A2：你可以使用 NVIDIA 的 nvidia-smi 命令来查看显存使用情况，或者在任务管理器的性能选项卡中查看 GPU 显存占用。

Q3：可以同时运行多个模型吗？
A3：可以，但会占用更多的内存和显存。建议根据你的硬件配置合理安排。

Q4：如何更新 Ollama？
A4：直接从官网下载最新版本的安装包，覆盖安装即可。你的模型不会被删除。

Q5：如何备份和迁移模型？
A5：模型默认存储在 C:\Users\用户名\.ollama\models 目录下。你可以直接复制这个目录到其他电脑的相同位置来迁移模型。

Q6：Open WebUI 支持连接多个 Ollama 服务吗？
A6：是的，你可以在 Open WebUI 的设置中添加多个 Ollama 连接，并在不同的服务之间切换。

Q7：RAG 功能支持扫描版 PDF 吗？
A7：目前不直接支持扫描版 PDF。你需要先使用 OCR 工具将扫描版 PDF 转换为可编辑的文本格式，然后再上传。

Q8：如何更新 Open WebUI 到最新版本？
A8：

docker stop open-webui
docker rm open-webui
docker pull ghcr.io/open-webui/open-webui:main
docker run -d -p 3000:3000 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Q9：Continue 扩展无法连接到 Open WebUI？
A9：检查 API 基础 URL 和 API 密钥是否正确；确保 Open WebUI 服务正在运行；检查防火墙是否阻止了连接。

Q10：Text Generator 插件生成内容时出错？
A10：检查 API 配置是否正确；确保模型名称正确；尝试降低最大令牌数设置。

Q11：如何切换回 Ollama 官方源？
A11：删除 OLLAMA_HOST 系统环境变量，然后重启 Ollama 服务。

Q12：自定义插件无法加载怎么办？
A12：检查插件文件结构是否正确；查看 Open WebUI 容器的日志获取错误信息；确保插件使用的 Python 版本与 Open WebUI 兼容。

Q13：Ollama API 支持跨域请求吗？
A13：默认支持跨域请求，无需额外配置。

Q14：企业部署时如何限制用户只能访问特定的知识库？
A14：在 Open WebUI 的知识库设置中，可以设置知识库的访问权限，只允许特定用户或用户组访问。

16. 总结与资源

Ollama 配合 Open WebUI 为个人和企业提供了一个零门槛、隐私安全、功能强大的本地大模型解决方案。通过本指南，你已经掌握了从安装、基础使用到高级功能、工具集成、性能优化、离线部署、API 开发和企业级部署的完整流程，能够充分发挥本地大模型的潜力，满足各种 AI 需求。

推荐资源：

文档版本：v2.0（2026年4月9日更新）
适用版本：Ollama 0.1.48+，Open WebUI 0.3.10+

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

TabPFN 深度技术解读：表格数据基础模型的颠覆性突破与工程化全景

avatar AtomGit开源社区
cover

5个C语言开源项目统治全球科技30年：今天却被AI逼到转型边缘？

avatar AtomGit开源社区

基于 KMP 实现一个跨平台音乐播放器

摘要：LynMusic是一款基于KMP技术开发的跨平台音乐播放器，支持安卓、iOS、macOS等多平台。开发者利用AI编程工具Codex完成了开发，解决了歌词搜索难、平台兼容性等问题。该播放器支持本地音乐、云盘导入、歌词分享、定时播放等功能，并适配车机、电视等设备。采用Kotlin Compose开发，相比Web方案性能更优。项目已开源，开发者分享了使用AI编程的心得，包括需求沟通、代码维护等经验

avatar AtomGit开源社区