Ollama 完全使用指南：从零开始在本地部署大模型

https://ollama.ai/public/og.png

引言

在当今的 AI 时代，大语言模型（LLM）已经渗透到各个领域。然而，将数据发送给第三方 API 往往会带来隐私泄露的风险和网络延迟的困扰。Ollama 的出现完美解决了这一问题。

Ollama 是一个开源的本地大模型部署工具，它简化了大型语言模型的运行和管理。通过简单的命令，我们就能在消费级设备上快速启动和运行诸如 Llama、DeepSeek、Qwen 等开源模型，无需复杂的环境配置 。本文将手把手带你掌握 Ollama 的使用，并结合多种编程语言的真实代码，展示如何将其集成到你的应用中。

---

第一章：初识 Ollama 与极速安装

1.1 什么是 Ollama？

简单来说，Ollama 就是一个大模型的"Docker"。它将模型权重、配置文件和环境打包在一起，让你通过几条命令就能拉起一个强大的 AI 服务。它支持 GPU 加速，并提供与 OpenAI 兼容的 API 接口，这意味着你可以像调用 ChatGPT 接口一样调用本地模型 。

1.2 跨平台安装

Ollama 支持主流操作系统，安装方式非常友好。

• macOS / Linux

  打开终端，执行以下命令，脚本会自动完成安装：

  bash

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

  小贴士：在 Linux 下，安装脚本会自动创建 systemd 服务，方便后台管理 。

• Windows

  访问 Ollama 官网 下载安装包，或使用 PowerShell 进行脚本安装：

  powershell

  Invoke-Webrequest -Uri "https://ollama.ai/install.ps1" -OutFile "install.ps1"
  .install.ps1

1.3 验证安装

安装完成后，打开终端输入以下命令查看版本号，确认安装成功：

bash

ollama --version

---

第二章：核心命令与模型管理

安装完成后，让我们通过实战来熟悉 Ollama 的核心操作。

2.1 下载并运行你的第一个模型

以 Meta 的 Llama 3.2 模型为例（这是目前对消费级硬件非常友好的模型），只需一行命令：

bash

ollama run llama3.2

系统会自动拉取模型，下载完成后直接进入对话界面。在这里，你可以像与 ChatGPT 聊天一样，直接在终端输入问题并按回车等待回答 。

2.2 常用命令速查表

掌握以下命令，你就掌握了 Ollama 80% 的日常操作 。

命令	作用描述	示例
ollama pull <模型名>	仅下载模型到本地，不立即运行	ollama pull deepseek-r1:7b
ollama list	列出本地已下载的所有模型	ollama list
ollama run <模型名>	运行指定模型（若本地没有，则先下载再运行）	ollama run qwen:7b
ollama ps	查看当前正在后台运行的模型	ollama ps
ollama stop <模型名>	停止正在运行的模型	ollama stop llama3.2
ollama rm <模型名>	删除本地指定的模型以释放磁盘空间	ollama rm llama3.2

2.3 优化模型存储路径（关键步骤！）

随着下载的模型增多，你会发现系统盘空间急剧减少。因为默认情况下，模型存储在系统盘的用户目录下 。

• Windows 默认路径 ：C:\Users\<用户名>\.ollama\models

• Linux/macOS 默认路径 ：~/.ollama/models

为了避免系统盘爆炸，我们需要迁移存储路径：

• Windows 用户：

  1. 右键"此电脑" -> "属性" -> "高级系统设置" -> "环境变量"。

  2. 新建系统变量，变量名：OLLAMA_MODELS，变量值：D:\ollama\models（你想存放的路径）。

  3. 重启电脑或终端。

• Linux/macOS 用户 ：

  编辑 shell 配置文件（如 .bashrc 或 .zshrc），添加以下内容：

  bash

  export OLLAMA_MODELS=/path/to/your/models
  source ~/.bashrc  # 使配置生效

---

第三章：将 Ollama 集成到你的应用中（多语言实战）

Ollama 最强大的地方在于它内置了 HTTP API 服务。启动 Ollama 服务后（通常在后台自动运行），它默认监听 11434 端口 。下面我们分别用三种主流语言调用它。

3.1 准备工作：启动服务

确保 Ollama 服务正在运行：

bash

ollama serve

通常情况下，只要你不手动关闭，Ollama 会作为后台服务常驻。

3.2 JavaScript/Node.js 实战

对于前端或 Node.js 开发者，Ollama 提供了官方的 ollama npm 包 。

安装依赖：

bash

npm install ollama

代码示例：流式对话

javascript

import ollama from 'ollama';

async function chatWithAI() {
  const message = { role: 'user', content: '用中文解释一下什么是量子计算' };

  // 开启流式响应，效果更接近真实的 ChatGPT
  const response = await ollama.chat({
    model: 'llama3.2', // 指定你下载的模型
    messages: [message],
    stream: true, // 开启流式
  });

  process.stdout.write('AI: ');
  for await (const part of response) {
    // 逐字输出回复内容
    process.stdout.write(part.message.content);
  }
  console.log(); // 换行
}

chatWithAI();

通过 stream: true，我们可以实现打字机效果，极大地提升用户体验 。

3.3 Java (Spring Boot) 实战

在企业级后端，Java 是主力语言。我们可以使用 OkHttp 或 RestTemplate 调用 Ollama 的 API 。

添加依赖（pom.xml）：

xml

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

代码示例：同步调用生成接口

java

import okhttp3.*;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;

public class OllamaJavaClient {
    private static final String OLLAMA_URL = "http://localhost:11434/api/generate";
    private final OkHttpClient client = new OkHttpClient();
    private final ObjectMapper mapper = new ObjectMapper();

    public String generate(String prompt) throws IOException {
        // 构建请求体
        String jsonBody = mapper.writeValueAsString(
            Map.of("model", "deepseek-r1:7b", "prompt", prompt, "stream", false)
        );

        RequestBody body = RequestBody.create(
            jsonBody, MediaType.parse("application/json; charset=utf-8")
        );

        Request request = new Request.Builder()
                .url(OLLAMA_URL)
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) throw new IOException("请求失败: " + response);

            String responseBody = response.body().string();
            // 解析 JSON，提取 response 字段
            JsonNode jsonNode = mapper.readTree(responseBody);
            return jsonNode.get("response").asText();
        }
    }

    public static void main(String[] args) throws IOException {
        OllamaJavaClient client = new OllamaJavaClient();
        String result = client.generate("写一首关于春天的五言绝句");
        System.out.println(result);
    }
}

此代码向 /api/generate 端点发送 POST 请求，并解析返回的 JSON 数据中的 response 字段 。

3.4 Go 语言实战：结构化输出

如果你需要模型返回严格的 JSON 格式以便程序处理，Go 语言的 agent-sdk-go 库提供了很好的结构化输出支持 。

代码示例：定义结构体并获取结构化数据

go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "github.com/Ingenimax/agent-sdk-go/examples/llm/ollama/structured_output" // 假设的导入路径
)

// 定义我们希望模型返回的数据结构
type Person struct {
    Name        string `json:"name" description:"人物的全名"`
    Profession  string `json:"profession" description:"主要职业"`
    Description string `json:"description" description:"简短的人物传记"`
    BirthDate   string `json:"birth_date,omitempty" description:"出生日期"`
}

func main() {
    ctx := context.Background()
    // 初始化 Ollama 客户端
    client := ollama.NewClient("http://localhost:11434")

    // 自动根据 Person 结构体生成 JSON Schema
    personFormat := structuredoutput.NewResponseFormat(Person{})

    // 请求模型生成结构化输出
    response, err := client.Generate(ctx, "介绍下著名科学家爱因斯坦", 
        ollama.WithResponseFormat(*personFormat))
    if err != nil {
        log.Fatal(err)
    }

    // 直接将结果解析为 Person 结构体
    var person Person
    json.Unmarshal([]byte(response), &person)

    fmt.Printf("姓名: %s\n职业: %s\n简介: %s\n", person.Name, person.Profession, person.Description)
}

通过 description 标签，我们可以指导模型如何填充字段，这对构建 Agent 应用至关重要 。

---

第四章：高级玩法------自定义模型 (Modelfile)

你是否觉得模型的回答风格太死板？或者希望它永远以"海盗"的口吻说话？Ollama 允许我们通过 Modelfile 来定制模型 。

4.1 创建自定义模型

假设我们基于 llama3.2 创建一个"海盗版"模型。

1. 创建一个文本文件，命名为 PirateModelfile，内容如下：

   text

   FROM llama3.2
   
   # 设置温度参数 (越高越有创造性)
   PARAMETER temperature 1.2
   
   # 设置系统提示词，规定模型的行为
   SYSTEM """
   你现在是一个脾气暴躁但经验丰富的老海盗。你说话必须带有海盗的口头禅，比如'啊哈！'、'该死的'、'我的宝藏'。
   你要用简短、粗鲁的海盗方式回答用户的所有问题。
   """

2. 根据这个文件创建新模型：

   bash

   ollama create pirate-model -f ./PirateModelfile

3. 运行你的专属模型：

   bash

   ollama run pirate-model

   提问："你好吗？"

   回答："啊哈！该死的，没看见老子正对着罗盘发愁吗，你这旱鸭子！"

通过调整 temperature、top_p 和 SYSTEM 提示词，你可以创造出无数种性格的 AI 。

---

第五章：图形化界面与生态集成

总是面对黑底白字的终端，时间久了难免枯燥。我们可以为 Ollama 套上一个漂亮的"外壳"------Open WebUI 。

5.1 部署 Open WebUI

Open WebUI 是一个功能丰富的自托管网页界面，支持多模型对话、RAG 检索增强生成等高级功能。使用 Docker 部署最为便捷：

bash

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

部署成功后，访问 http://localhost:3000，你就可以在一个酷似 ChatGPT 的界面中，与你的本地模型聊天了 。

---

常见问题排雷 (FAQ)

Q1: 下载模型卡在 99% 怎么办？

A: 这是网络波动导致的常见问题。直接按 Ctrl+C 取消下载，然后重新执行 ollama pull <模型名>。Ollama 支持断点续传，会继续完成下载 。

Q2: 运行模型时报错"显存不足"？

A:

• 尝试选用量化版本模型，如 deepseek-r1:7b 的 q4_K_M 版本，它对显存要求更低 。

• 关闭其他占用显存的程序（如浏览器、游戏）。

Q3: 局域网内其他设备如何访问我的 Ollama？

A: 默认 Ollama 只监听本地 (127.0.0.1)。你需要设置环境变量让监听所有网络接口 ：

bash

# Linux/macOS
export OLLAMA_HOST=0.0.0.0:11434
ollama serve

注意：在没有安全防护的局域网开放服务需谨慎，建议配合防火墙使用。

---

总结

Ollama 极大地降低了普通人接触和使用大模型的门槛。从最初的一键安装，到终端里的趣味对话，再到通过 API 将其集成到多语言应用中，最后到自定义模型人格化------我们一步步见证了本地 AI 的魔力。

无论你是想保护数据隐私的开发者，还是想探索 AI 边界的爱好者，Ollama 都是你不容错过的利器。希望这篇指南能帮助你在本地 AI 的世界里扬帆起航。