Ollama 本地 LLM 管理与 WebUI 及 Python/Java API 应用

Ollama 简介与定位

Ollama 是一个开源的 LLM（大型语言模型）服务工具，旨在简化在本地运行大语言模型的流程，降低使用门槛。它使得开发者、研究人员和爱好者能够在本地环境快速实验、管理和部署最新的开源大模型，如 Qwen2、Llama3、Phi3、Gemma2 等。

Ollama 与 Llama 的关系：Llama 是 Meta 公司开源的大语言模型系列，而 Ollama 是大语言模型（不限于 Llama）便捷的管理和运维工具。两者名称相似但功能不同，Ollama 支持多种模型格式和管理方式。

Ollama 架构示意

Ollama 安装与环境配置

1. 下载安装

访问官网首页可直接下载 Ollama 安装程序，支持 Windows、macOS 和 Linux 系统。安装过程与普通软件类似，安装完成后建议配置以下环境变量以优化性能和安全。

2. 常用系统参数设置

建议在系统环境变量中进行如下配置：

OLLAMA_MODELS：模型文件存放目录。默认位于用户目录（Windows: C:\Users\%username%\.ollama\models，Linux/Mac: ~/.ollama/models）。若 C 盘空间紧张，建议修改至其他分区（如 D:\OllamaModels），避免磁盘爆满影响系统运行。
OLLAMA_HOST：服务监听地址。默认为 127.0.0.1（仅本机访问）。若需局域网内其他设备调用，建议设置为 0.0.0.0，但需注意安全风险，生产环境应配合防火墙策略。
OLLAMA_PORT：服务端口。默认为 11434。若端口冲突可修改为其他端口（如 8080）。
OLLAMA_ORIGINS：HTTP 请求来源白名单。半角逗号分隔。本地开发可设为 * 允许所有来源，生产环境建议限制具体域名。
OLLAMA_KEEP_ALIVE：模型加载后的存活时间。默认为 5m（5 分钟）。可设置为 24h 保持常驻内存以提高响应速度，或设为 0 以便请求结束后立即卸载释放显存。
OLLAMA_NUM_PARALLEL：并发请求数。默认为 1。可根据硬件资源调整，多 GPU 环境下可适当增加以提升吞吐量。
OLLAMA_MAX_QUEUE：请求队列长度。默认为 512。超过此长度的请求将被丢弃，高并发场景下需根据服务器负载调整。
OLLAMA_DEBUG：调试日志开关。研发阶段可设为 1 输出详细日志，便于排查连接或推理问题。
OLLAMA_MAX_LOADED_MODELS：同时加载的最大模型数。默认为 1。若需频繁切换模型，可适当调高，但受限于显存大小。

管理本地已有大模型

Ollama 提供了丰富的命令行工具来管理本地模型。

1. 查看模型列表

ollama list

输出示例：

NAME            ID              SIZE    MODIFIED
gemma2:9b       c19987e1e6e2    5.4 GB  7 days ago
qwen2:7b        e0d4e1163c58    4.4 GB  10 days ago

显示本地已下载的模型名称、ID、大小及修改时间。

2. 删除模型

ollama rm <模型名称>

例如：ollama rm gemma2:9b。删除后需重新拉取才能再次使用。

3. 启动对话

ollama run <模型名称>

进入终端交互模式。支持多行输入（使用三引号包裹）、清除上下文（/clear）、退出对话（/bye）及查看模型详情（/show info）。

4. 查看运行中模型

ollama ps

显示当前占用显存的模型进程信息，包括 CPU/GPU 占用率及剩余存活时间。

5. 复制模型

ollama cp <源模型名> <新模型名>

用于创建同名不同版本或重命名的模型副本，方便进行微调或测试。

导入模型到本地的三种方式

方式一：从远程仓库拉取（推荐）

直接使用 pull 命令从 Ollama 官方库下载模型。

ollama pull qwen2:0.5b

模型名称格式为 模型名称：参数规格。若未指定规格，默认下载 latest 版本。支持增量更新，即本地存在部分文件时仅下载缺失部分。

注意：GLM4-9B 模型自 Ollama 0.2.0 版本起支持，命令为 ollama pull glm4:9b。

方式二：导入 GGUF 权重文件

若已拥有 HuggingFace 或 ModelScope 下载的 .gguf 文件，可通过 Modelfile 导入。

在模型文件目录下创建 Modelfile，内容如下：
```
FROM ./Meta-Llama-3-8B-Instruct.Q4_K_M.gguf
```

执行创建命令：

ollama create Llama-3-8B -f ./Modelfile

此方法适合自定义量化模型或私有模型迁移。

方式三：导入 Safetensors 权重文件

对于原始 safetensors 格式模型，需先转换为 llama.cpp 兼容格式。

克隆模型仓库并转换格式：

git clone https://www.modelscope.cn/rubraAI/Mistral-7B-Instruct-v0.3.git Mistral-7B
python llm/llama.cpp/convert.py ./Mistral-7B --outtype f16 --outfile Mistral-7B-v0.3.bin

量化处理：

llm/llama.cpp/quantize Mistral-7B-v0.3.bin Mistral-7B-v0.3_Q4.bin q4_0

创建 Modelfile 并导入：

FROM Mistral-7B-v0.3_Q4.bin

ollama create Mistral-7B-v0.3 -f ./Modelfile

基于 WebUI 部署可视化对话界面

Ollama 自带终端界面功能有限，推荐使用 ollama-webui 提供图形化体验。

安装 Node.js 环境。

克隆项目代码：

git clone https://github.com/ollama-webui/ollama-webui-lite ollama-webui
cd ollama-webui

配置镜像源加速依赖下载：

npm config set registry http://mirrors.cloud.tencent.com/npm/

安装依赖并启动：
```
npm install
npm run dev
```

启动成功后，浏览器访问 http://localhost:3000 即可使用。

Ollama 客户端 API 应用

Ollama 默认提供 HTTP API 接口，支持 generate（生成）和 chat（对话）两种模式。

1. HTTP 原生调用

curl http://localhost:11434/api/generate -d '{
  "model": "qwen:0.5b",
  "prompt": "为什么天空是蓝色的？"
}'

2. Python API 集成

安装依赖包：

pip install ollama

流式输出示例：

import ollama

def api_generate(text: str):
    print(f'提问：{text}')
    stream = ollama.generate(
        stream=True,
        model='qwen:7b',
        prompt=text,
    )
    for chunk in stream:
        if not chunk['done']:
            print(chunk['response'], end='', flush=True)
        else:
            print('\n')
            print(f'总耗时：{chunk["total_duration"]}')

if __name__ == '__main__':
    api_generate('天空为什么是蓝色的？')

3. Java API 集成 (Spring Boot)

在 pom.xml 中添加依赖：

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
  <version>1.0.0</version>
</dependency>

配置文件 application.properties：

server.port=8088
spring.application.name=NTopicBootX
spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=qwen:0.5b

Controller 示例：

@RestController
public class OllamaClientController {

    @Autowired
    private OllamaChatClient ollamaChatClient;

    @GetMapping("/ollama/chat/v1")
    public String ollamaChat(@RequestParam String msg) {
        return this.ollamaChatClient.call(msg);
    }
}

常见问题与最佳实践

1. 显存不足

若遇到 OOM（Out Of Memory）错误，请尝试选择参数量更小的模型（如 0.5b 或 1.5b 版本），或使用更高量化的模型（如 Q4_K_M）。

2. 网络访问受限

若无法拉取模型，检查代理设置。可在环境变量中配置 HTTPS_PROXY 或使用国内镜像源加速。

3. 安全性建议

将 OLLAMA_HOST 设置为 0.0.0.0 时，务必确保服务器防火墙仅允许受信任 IP 访问，防止 API 被滥用导致算力消耗。

4. 性能调优

在高并发场景下，适当增加 OLLAMA_NUM_PARALLEL 和 OLLAMA_MAX_QUEUE 可提升吞吐量，但需监控 GPU 利用率，避免过载导致推理延迟增加。