Ollama教程：本地LLM管理、WebUI对话、Python/Java客户端API应用

在前面有关大模型应用的文章中，多次使用了**Ollama**来管理和部署本地大模型（包括：**Qwen2**、**Llama3**、**Phi3**、**Gemma2**等），但对**Ollama**这个非常方便管理本地大模型的软件的介绍却很少。

目前，清华和智谱 AI 联合发布开源的**GLM4-9B**大模型也能支持**Ollama**进行本地部署了（本地部署 GLM-4-9B 清华智谱开源大模型方法和对话效果体验），**Ollama**支持的大模型越多越普及，对于的应用也就越多。为了降低大家查阅资料等学习时间，今天尝试着对 Ollama 进行一次详细完整介绍。毕竟也在不断学习中，若有疏漏或者错误之处，还请各位朋友多多指正，谢谢大家。

本文将分为以下章节对 Ollama 进行介绍：

1.  Ollama 基本介绍，它的作用是什么
2.  Ollama 软件安装、一些常用的系统参数设置
3.  Ollama 管理本地已有大模型（包括终端对话界面）
4.  Ollama 导入模型到本地的三种方式：直接从 Ollama 远程仓库拉取、通过 GGUF 模型权重文件导入到本地、通过 safetensors 模型权限文件导入到本地
5.  基于 WebUI 部署 Ollama 可视化对话界面
6.  Ollama 客户端 API 应用，包括 Python API 和 Java API 接口应用

## Ollama 是什么，它与 Llama 有什么关系？

**Ollama**官网：https://ollama.com/

官方网站的介绍就一句话：**Get up and running with large language models.** （开始使用大语言模型。）

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

**Ollama**支持的大语言模型列表，可通过搜索模型名称查看：https://ollama.com/library

**Ollama**官方 GitHub 源代码仓库：https://github.com/ollama/ollama/

**Llama**是 Meta 公司开源的备受欢迎的一个通用大语言模型，和其他大模型一样，**Llama**可以通过**Ollama**进行管理部署和推理等。

因此，Ollama与Llama的关系：Llama是大语言模型，而Ollama是大语言模型（不限于Llama模型）便捷的管理和运维工具，它们只是名字后面部分恰巧相同而已！

![](https://doc.xiqi.site/media/202407/2024-07-23_060009_8801940.20320930936749904.webp)

## Ollama 安装和常用系统参数设置

在官网首页，我们可以直接下载**Ollama**安装程序（支持 Windows/MacOS/Linux）：https://ollama.com/

**Ollama**的安装过程，与安装其他普通软件并没有什么两样，安装完成之后，有几个常用的系统**环境变量**参数建议进行设置：

模型文件存放目录，默认目录为当前用户目录（Windows 目录：C:\\Users%username%.ollama\\models，MacOS 目录：~/.ollama/models，Linux 目录：/usr/share/ollama/.ollama/models），如果是 Windows 系统**建议修改**（如：D:\\OllamaModels），避免 C 盘空间吃紧。

Ollama 服务监听的网络地址，默认为**127.0.0.1**，如果允许其他电脑访问 Ollama（如：局域网中的其他电脑），**建议设置**成**0.0.0.0**，从而允许其他网络访问。

Ollama 服务监听的默认端口，默认为**11434**，如果端口有冲突，可以修改设置成其他端口（如：**8080**等）。

HTTP 客户端请求来源，半角逗号分隔列表，若本地使用无严格要求，可以设置成星号，代表不受限制。

大模型加载到内存中后的存活时间，默认为**5m**即 5 分钟（如：纯数字如 300 代表 300 秒，0 代表处理请求响应后立即卸载模型，任何负数则表示一直存活）；我们可设置成**24h**，即模型在内存中保持 24 小时，提高访问速度。

请求处理并发数量，默认为**1**，即单并发串行处理请求，可根据实际情况进行调整。

请求队列长度，默认值为**512**，可以根据情况设置，超过队列长度请求被抛弃。

输出 Debug 日志标识，应用研发阶段可以设置成**1**，即输出详细日志信息，便于排查问题。

1.  **OLLAMA\_MAX\_LOADED\_MODELS**：

最多同时加载到内存中模型的数量，默认为**1**，即只能有 1 个模型在内存中。

## Ollama 管理本地已有大模型

【展示本地大模型列表：ollama list】

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

可以看到，本地有 2 个大模型，它们的名称（**NAME**）分别为**gemma2:9b**和**qwen2:7b**。

【删除单个本地大模型：ollama rm 本地模型名称】

```
>ollama rm gemma2:9b
deleted 'gemma2:9b'

>ollama list
NAME            ID              SIZE    MODIFIED
qwen2:7b        e0d4e1163c58    4.4 GB  10 days ago
```

通过rm命令删除了**gemma2:9b**大模型之后，再次通过list命令查看，本地只有**qwen2:7b**一个大模型了。

【启动本地模型：ollama run 本地模型名】

```
>ollama run qwen2:0.5b
>>>
```

启动成功之后，就可以通过终端对话界面进行对话了（本命令下面也会讲到，其他详细暂且忽略）。

【查看本地运行中模型列表：ollama ps】

```
>ollama ps
NAME            ID              SIZE    PROCESSOR       UNTIL
qwen2:0.5b      6f48b936a09f    693 MB  100% CPU        4 minutes from now
```

通过ps命名可以看到，本地**qwen2:0.5b**大模型正在运行中。

【复制本地大模型：ollama cp 本地存在的模型名 新复制模型名】

```
>ollama cp qwen2:0.5b Qwen2-0.5B
copied 'qwen2:0.5b' to 'Qwen2-0.5B'

>ollama list
NAME                    ID              SIZE    MODIFIED
Qwen2-0.5B:latest       6f48b936a09f    352 MB  4 seconds ago
qwen2:0.5b              6f48b936a09f    352 MB  29 minutes ago
qwen2:7b                e0d4e1163c58    4.4 GB  10 days ago
```

上面cp命令，把本地**qwen2:0.5b**复制了一份，新模型名为**Qwen2-0.5B**

下面介绍三种通过 Ollama 下载到本地大模型方式：

1.  方式一：直接通过 Ollama 远程仓库下载，这是最直接的方式，也是最推荐、最常用的方式。
2.  方式二：如果已经有 GGUF 模型权重文件了，不想重新下载，也可以通过 Ollama 把该文件直接导入到本地（不推荐、不常用）。
3.  方式三：如果已经有 safetensors 模型权重文件，也不想重新下载，也可以通过 Ollama 把该文件直接导入到本地（不推荐、不常用）。

## 方式一：Ollama 从远程仓库下载大模型到本地

【下载或者更新本地大模型：ollama pull 本地/远程仓库模型名称】

本pull命令从 Ollama 远程仓库完整下载或增量更新模型文件，模型名称**格式**为：**模型名称:参数规格**；如ollama pull qwen2:0.5b 则代表从 Ollama 仓库下载**qwen2**大模型的**0.5b**参数规格大模型文件到本地磁盘：

![](https://doc.xiqi.site/media/202407/2024-07-23_060010_1190460.8359225361549296.png)

如果参数规格标记为latest则代表为默认参数规格，下载时**可以**不用指定，如**Qwen2**的**7b**被标记为latest，则ollama pull qwen2和ollama pull qwen2:7b这 2 个命令的意义是一样的，都下载的为**7b**参数规格模型。为了保证后续维护方便、避免误操作等，**建议**不管是否为默认参数规格，我们下载命令中均明确参数规格。

值得一提的是，今天开始**GLM4**支持 Ollama 部署和推理，特意列出它的下载命令：ollama pull glm4:9b（和其他模型相比，其实并没有特殊支出）。需要注意的是：Ollama 最低版本为**0.2.0**才能支持**GLM4**大模型！

![](https://doc.xiqi.site/media/202407/2024-07-23_060010_0603110.06250597235238209.png)

GLM4模型列表

```
>ollama pull qwen2:0.5b
pulling manifest
pulling manifest
pulling manifest
pulling manifest
pulling manifest
pulling 8de95da68dc4... 100% ▕████████████████████████▏ 352 MB
pulling 62fbfd9ed093... 100% ▕████████████████████████▏  182 B
pulling c156170b718e... 100% ▕████████████████████████▏  11 KB
pulling f02dd72bb242... 100% ▕████████████████████████▏   59 B
pulling 2184ab82477b... 100% ▕████████████████████████▏  488 B
verifying sha256 digest
writing manifest
removing any unused layers
success

>ollama list
NAME            ID              SIZE    MODIFIED
qwen2:0.5b      6f48b936a09f    352 MB  9 minutes ago
qwen2:7b        e0d4e1163c58    4.4 GB  10 days ago
```

若本地不存在大模型，则**下载**完整模型文件到本地磁盘；若本地磁盘存在该大模型，则**增量**下载大模型更新文件到本地磁盘。

从上面最后的list命令结果可以看到，本地存在了**qwen2:0.5b**这个名称的大模型。

【下载且运行本地大模型：ollama run 本地/远程仓库模型名称】

```
>ollama run qwen2:0.5b
>>>
```

若本地不存在大模型，则**下载**完整模型文件到本地磁盘（类似于pull命令），然后**启动**大模型；若本地存在大模型，则直接启动（不进行更新）。

启动成功后，默认为终端对客界面：

![](https://doc.xiqi.site/media/202407/2024-07-23_060010_0942090.7410289152038884.png)

1.  若需要输入多行文本，需要用**三引号**包裹，如："""这里是多行文本"""
2.  /clear清除对话上下文信息
3.  /bye则退出对话窗口
4.  /set parameter num\_ctx 4096可设置窗口大小为 4096 个 Token，也可以通过请求设置，如：curl <http://localhost:11434/api/generate> -d '{ "model": "qwen2:7b", "prompt": "Why is the sky blue?", "options": { "num\_ctx": 4096 }}'
5.  /show info可以查看当前模型详情： ，

```
>>> /show info
  Model
        arch                    qwen2
        parameters              494.03M
        quantization            Q4_0
        context length          32768
        embedding length        896

Parameters
        stop    "<|im_start|>"
        stop    "<|im_end|>"

License
        Apache License
        Version 2.0, January 2004
```

## 方式二：Ollama 导入 GGUF 模型文件到本地磁盘

若我们已经从 HF 或者 ModeScope 下载了 GGUF 文件（文件名为：**Meta-Llama-3-8B-Instruct.Q4\_K\_M.gguf**），在我们存放Llama3-8B的 GGUF 模型文件目录中，创建一个文件名为Modelfile的文件，该文件的内容如下：

```
FROM ./Meta-Llama-3-8B-Instruct.Q4_K_M.gguf
```

然后，打开终端，执行命令导入模型文件：ollama create 模型名称 -f ./Modelfile

```
>ollama create Llama-3-8B -f ./Modelfile
transferring model data
using existing layer sha256:647a2b64cbcdbe670432d0502ebb2592b36dd364d51a9ef7a1387b7a4365781f
creating new layer sha256:459d7c837b2bd7f895a15b0a5213846912693beedaf0257fbba2a508bc1c88d9
writing manifest
success
```

导入成功之后，我们就可以通过list命名，看到名为**Llama-3-8B**的本地模型了，后续可以和其他模型一样进行管理了。

## 方式三：Ollama 导入 safetensors 模型文件到到本地磁盘

官方操作文档：https://ollama.fan/getting-started/import/#importing-pytorch-safetensors

若我们已经从 HF 或者 ModeScope 下载了 safetensors 文件（文件目录为：**Mistral-7B**），

```
git lfs install

git clone https://www.modelscope.cn/rubraAI/Mistral-7B-Instruct-v0.3.git Mistral-7B
```

然后，我们转换模型（结果：Mistral-7B-v0.3.bin）：

```
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
```

最后，通过 Ollama 导入到本地磁盘，创建Modelfile模型文件：

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

执行导入命令，导入模型文件：ollama create 模型名称 -f ./Modelfile

```
>ollama create Mistral-7B-v0.3 -f ./Modelfile
transferring model data
using existing layer sha256:647a2b64cbcdbe670432d0502ebb2592b36dd364d51a9ef7a1387b7a4365781f
creating new layer sha256:459d7c837b2bd7f895a15b0a5213846912693beedaf0257fbba2a508bc1c88d9
writing manifest
success
```

导入成功之后，我们就可以通过list命名，看到名为**Mistral-7B-v0.3**的本地模型了，后续可以和其他模型一样进行管理了。

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

**Ollama**自带控制台对话界面体验总归是不太好，接下来部署 Web 可视化聊天界面：

1.  下载并安装 Node.js 工具：https://nodejs.org/zh-cn
2.  下载ollama-webui工程代码：git clone https://github.com/ollama-webui/ollama-webui-lite ollama-webui
3.  切换ollama-webui代码的目录：cd ollama-webui
4.  设置 Node.js 工具包镜像源（下载提速）：npm config set registry http://mirrors.cloud.tencent.com/npm/
5.  安装 Node.js 依赖的工具包：npm install
6.  最后，启动 Web 可视化界面：npm run dev

![](https://doc.xiqi.site/media/202407/2024-07-23_060010_0488010.9219052747613861.webp)

Ollam WebUI启动成功

如果看到以上输出，代表 Web 可视化界面已经成功了！

浏览器打开 Web 可视化界面：http://localhost:3000/

![](https://doc.xiqi.site/media/202407/2024-07-23_060009_9477000.13643346781142585.webp)

Ollam WebUI对话界面

## Ollama 客户端：HTTP 访问服务

Ollama 默认提供了generate和chat这 2 个原始的 API 接口，使用方式如下：

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

```
curl http://localhost:11434/api/chat -d '{
  "model": "qwen:7b",
  "messages": [
    { "role": "user", "content": "为什么天空是蓝色的？" }
  ]
}'
```

接下来的**Python**和**Java**客户端应用，都是对这 2 个接口的封装。

## Ollama 客户端：Python API 应用

我们把 Ollama 集成到 Python 应用中，只需要以下简单 2 步即可：

**第一步**，安装 Python 依赖包：

```
pip install ollama
```

**第二步**，使用 Ollama 接口，stream=True代表按照流式输出：

```
import ollama

# 流式输出
def api_generate(text:str):
  print(f'提问：{text}')

stream = ollama.generate(
    stream=True,
    model='qwen:7b',
    prompt=text,
    )

print('-----------------------------------------')
  for chunk in stream:
    if not chunk['done']:
      print(chunk['response'], end='', flush=True)
    else:
      print('\n')
      print('-----------------------------------------')
      print(f'总耗时：{chunk['total_duration']}')
      print('-----------------------------------------')

if __name__ == '__main__':
  # 流式输出
  api_generate(text='天空为什么是蓝色的？')

# 非流式输出
  content = ollama.generate(model='qwen:0.5b', prompt='天空为什么是蓝色的？')
  print(content)
```

## Ollama 客户端：Java API 应用（SpringBoot 应用）

我们也可以把 Ollama 集成到 SpringBoot 应用中，只需要以下简单 3 步即可：

**第一步**，在总pom.xml中新增 SpringBoot Starter 依赖：

```
<dependency>
  <groupId>io.springboot.ai</groupId>
  <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
  <version>1.0.0</version>
</dependency>
```

**第二步**，在 SpringBoot 配置文件application.properties中增加 Ollama 配置信息：

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

配置文件指定了 Ollama API 地址和端口，同时指定了默认模型**qwen:0.5b**（注意：模型需要在本地已经存在）

**第三步**，使用OllamaChatClient进行文字生成或者对话：

```
import org.springframework.ai.chat.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.ollama.OllamaChatClient;
import org.springframework.ai.ollama.api.OllamaOptions;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class OllamaClientController {

@Autowired
    @Qualifier("ollamaChatClient")
    private OllamaChatClient ollamaChatClient;

/**
     * http://localhost:8088/ollama/chat/v1?msg=天空为什么是蓝色的？
     */
    @GetMapping("/ollama/chat/v1")
    public String ollamaChat(@RequestParam String msg) {
        return this.ollamaChatClient.call(msg);
    }

/**
     * http://localhost:8088/ollama/chat/v2?msg=人为什么要不断的追求卓越？
     */
    @GetMapping("/ollama/chat/v2")
    public Object ollamaChatV2(@RequestParam String msg) {
        Prompt prompt = new Prompt(msg);
        ChatResponse chatResponse = ollamaChatClient.call(prompt);
        return chatResponse;
    }

/**
     * http://localhost:8088/ollama/chat/v3?msg=你认为我的文章如何？
     */
    @GetMapping("/ollama/chat/v3")
    public Object ollamaChatV3(@RequestParam String msg) {
        Prompt prompt = new Prompt(
                msg,
                OllamaOptions.create()
                        .withModel("qwen:0.5b")
                        .withTemperature(0.4F));
        ChatResponse chatResponse = ollamaChatClient.call(prompt);
        return chatResponse.getResult().getOutput().getContent();
    }
}
```

以上是 Java 客户端的简单样例，我们可以通过OllamaChatClient访问 Ollama 接口，既可以使用默认大模型，也可以在参数指定模型名称！