Ollama 入门指南：本地大模型实践

Ollama 是一个让你能在自己电脑上轻松运行开源大模型（LLM）的工具。对于开发者来说，它就像一个本地的“模型服务器”，能帮你快速搭建和测试需要 AI 能力的应用，而无需依赖外部云服务。本指南将带你快速上手 Ollama，了解它的核心概念，并提供可以直接运行的代码示例。

快速入门：安装与运行

Ollama 的安装非常直接，支持主流操作系统。

步骤 1：安装 Ollama

从 Ollama 官网下载安装包手动安装，或者在终端中运行官方安装脚本。

安装完成后，Ollama 会在后台作为一个服务运行。在 macOS 上，你会在菜单栏看到一个小图标；在 Windows 上，它会出现在系统托盘。

步骤 2：下载并运行一个模型

接下来，我们下载一个模型并与之交互。可以从官网查找模型，这里以 qwen3:8b 为例

1. 打开终端 (Terminal / PowerShell)。

2. 运行以下命令来下载并启动模型：

   ollama run qwen3:8b
   

   这条命令会做两件事：

   • 如果本地没有 qwen3:8b 模型，它会自动从 Ollama 的模型库中下载（第一次运行会比较慢）。
   • 下载完成后，它会直接进入一个交互式的对话界面。

   你会看到类似下面的输出，表示你可以开始对话了：

   >>> Send a message (/? for help)
   

关于模型大小的说明

你可能注意到了 qwen3:8b 中的 8b，它代表模型的规模。

• 4b / 8b / 14b：这些数字表示模型的参数量（Billion，十亿）。例如，8b 就是 80 亿参数。
• 参数量越大：通常意味着模型“知道”的更多，回答质量更高，逻辑推理能力更强。
• 参数量越小：运行速度更快，对电脑配置（特别是显存和内存）的要求也越低。

对于入门者，3b 到 8b 范围的模型是一个很好的起点，它们在大部分现代笔记本电脑上都能流畅运行。

显存/内存建议

• 3B/4B 模型：至少需要 8GB 内存。
• 7B/8B 模型：建议有 16GB 内存。如果你有显存大于 8GB 的独立显卡（如 NVIDIA RTX 3060 或更高），体验会更好。
• 13B 及以上模型：建议有 32GB 内存或 16GB 以上显存。

Ollama 会自动检测并优先使用 GPU，如果你的电脑有兼容的显卡，它会获得显著的加速。

核心用法：与模型对话

命令行直接交互

在 ollama run 启动的交互界面中，你可以直接输入问题并获得回答。

>>> 你好，请用 JavaScript 写一个函数，计算斐波那契数列的第 n 项。

当然，这是一个使用递归和记忆化来计算斐波那Edo数列的 JavaScript 函数：

... (此处省略代码输出) ...

>>> /bye

• 输入 /? 可以查看所有可用的命令。
• 输入 /bye 或按 Ctrl+D 可以退出当前对话。

指定系统提示 (System Prompt )

你可以通过 /set system 命令在对话开始前添加“系统提示词”，为模型设定一个“角色”或“行为准则”。

# 启动模型
ollama run qwen:8b

# 进入交互界面后，设置系统提示
>>> /set system 你是一个资深的前端开发专家，回答问题时请提供代码示例。

>>> 现在请解释一下什么是 "props"。

这样，模型后续的回答都会遵循你设定的专家角色。

调整常用参数

你还可以在运行时调整一些影响模型输出的参数，例如：

• temperature (温度)：控制输出的随机性。值越高（如 0.8），回答越有创造性；值越低（如 0.2），回答越稳定和保守。
• num_ctx (上下文长度)：模型能“记住”的对话历史长度（以 token 计）。

在交互界面中，可以使用 /set parameter 来调整它们。

>>> /set parameter temperature 0.3
Set temperature to 0.3

或者，你也可以在 run 命令中一次性传入。

ollama run qwen:8b --set-parameter temperature=0.2

API 服务：将 Ollama 集成到你的代码中

Ollama 的核心魅力在于它将本地模型封装为标准的 REST API。默认情况下，Ollama 服务在 http://localhost:11434 上运行。

启动后台服务

通常情况下，当你安装并首次运行 Ollama 应用后，服务就会在后台自动启动。如果你想手动控制，可以在终端执行：

# 启动服务 (它会保持在前台运行，直到你按 Ctrl+C)
ollama serve

你可以通过访问 http://localhost:11434/ 来确认服务是否正在运行。如果看到 "Ollama is running"，说明一切正常。

两种主流 API Endpoint

Ollama 提供了两种主要的 API 端点（Endpoint）用于生成文本：

1. /api/generate：基础的生成接口，适用于简单的“一次性”问答。
2. /v1/chat/completions：兼容 OpenAI 的聊天接口。这是我们最推荐使用的接口，因为它允许你使用 openai-node 这样的流行库来与本地模型交互，就像调用 GPT-4 一样。

示例 1：使用 cURL 调用 API

我们先用 cURL 这个命令行工具来快速测试一下 API。

使用 /api/generate (基础接口)

这是一个简单的 POST 请求，发送一个 prompt。

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "为什么天空是蓝色的？请简要回答。",
  "stream": false
}'

"stream": false 表示我们希望一次性接收完整的回答，而不是以数据流的形式。

使用 /v1/chat/completions (OpenAI 兼容会话接口)

这个接口的结构和 OpenAI 的完全一致，使用 messages 数组来传递对话历史。

curl http://localhost:11434/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "qwen3:8b",
  "messages": [
    {
      "role": "system",
      "content": "你是一个乐于助人的AI助手。"
    },
    {
      "role": "user",
      "content": "你好，请问你是谁？"
    }
  ],
  "stream": false
}'

示例 2：在 NodeJS 中调用

在服务端调用 Ollama 接口。

方式一：使用原生 fetch

现代 Node.js 内置了 fetch API，无需安装任何依赖即可调用。

// file: ollama-test.js
async function main() {
  const response = await fetch('http://localhost:11434/api/chat', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'qwen3:8b',
      messages: [{ role: 'user', content: '请给我写一首关于春天的五言绝句。' }],
      stream: false, // 为了简单起见，先不使用流式输出
    }),
  });

  if (!response.ok) {
    console.error('Error:', response.statusText);
    return;
  }

  const data = await response.json();
  console.log(data.message.content);
}

main();

在终端运行 node ollama-test.js，你将看到模型生成的诗句。

方式二：使用 ollama 包

这是最优雅的方式，本示例使用官方包 ollama。也有一些不错的三方包可自行学习使用，如 @langchain/ollama

1. 初始化项目

   mkdir ollama-study
   cd ollama-study
   pnpm init
   

2. 修改 package.json，使用 ES Module

   {
     ...
     "type": "module",
   }
   

3. 安装 Ollama 包

   pnpm add ollama
   

4. 新建 index.js 文件

   import ollama from 'ollama'
   
   const response = await ollama.chat({
    model: 'qwen3:8b',
    messages: [{role: 'user', content: '你好'}],
   })
   console.log(response.message.content)
   

   或使用下面流式示例

   import ollama from "ollama";
   
   const response = await ollama.chat({
     model: "qwen3:8b",
     messages: [{ role: "user", content: "你好" }],
     stream: true,
   });
   
   for await (const chunk of response) {
     process.stdout.write(chunk.message.thinking || chunk.message.content || "");
   }
   

5. 运行（推荐 node 18+）

   node index.js
   

   你会看到控制台输出

   你好！有什么我可以帮助你的吗？
   

模型管理

Ollama 提供了一套简单的命令行工具来管理你的本地模型。

命令	说明
ollama list	列出所有已下载到本地的模型及其大小、上次修改时间等信息。
ollama pull <model_name>	下载一个新模型，例如 ollama pull ``qwen3:8b。
ollama rm <model_name>	删除一个本地模型以释放硬盘空间，例如 ollama rm qwen``3``:``8``b。
ollama cp <source> <destination>	复制一个模型，相当于给它起一个别名。例如， ollama cp ``qwen:8b`` my- ``qwen。

自定义你的模型：Modelfile

Ollama 允许你通过一个名为 Modelfile 的文件来创建自定义模型。这很像 Dockerfile，你可以基于一个现有模型，添加你自己的配置。

一个最简单的 Modelfile 如下：

# file: Modelfile

# 1. 选择一个基础模型
FROM llama3

# 2. 设置一个系统提示，定义模型的角色和行为
SYSTEM """
你是一个代码审查机器人。你的任务是检查代码中的潜在 bug、不符合最佳实践的地方，并提出具体的、有建设性的修改建议。请总是以简洁、专业的语气回答。
"""

# 3. 调整模型的默认参数
PARAMETER temperature 0.2
PARAMETER num_ctx 4096

然后，使用以下命令基于这个文件创建一个新模型：

# -f 指定 Modelfile 的路径
# 'code-reviewer' 是你给新模型起的名字
ollama create code-reviewer -f ./Modelfile

创建成功后，你就可以像使用其他模型一样运行它了：

ollama run code-reviewer

常见问题

问：Ollama和OpenAI/通义这些云服务有什么区别？

主要区别在于运行位置和数据隐私。Ollama 在你自己的电脑上运行，数据完全私有，不联网也能用，而且免费。云服务则在服务商的服务器上运行，功能更强大、模型更新快，但需要联网、付费，且数据会发送到云端。

问：7B/13B 是什么？我电脑能跑吗？

这是模型参数量的单位，7B=70亿。参数越多，模型通常越智能，但也越消耗资源。

• 8GB 内存电脑：适合跑 3B-4B 模型。
• 16GB 内存电脑：可以流畅运行 7B-8B 模型。
• 32GB+ 内存或有大 显存 ****GPU：可以尝试 13B 及以上模型。

问：为什么响应慢/占用高？如何优化？

慢通常因为模型太大或电脑配置不足。优化方法：

1. 换用更小的模型：如 qwen2:1.5b。
2. 使用量化模型：Ollama 模型库中的模型大多是经过量化（Quantization）的，量化会牺牲一点精度来大幅降低模型大小和资源占用。通常默认下载的就是合适的量化版本。
3. 确保 GPU 生效：运行 ollama ps 查看 PROCESSOR 列是否显示 GPU。
4. 关闭其他耗资源程序。

问：能离线吗？是否泄露代码？

完全可以离线使用。一旦模型下载完成，Ollama 的所有操作都在本地进行，不会向任何外部服务器发送你的输入数据（如代码、问题）或模型的输出结果。数据隐私是 Ollama 的核心优势之一。

问：如何与 VSCode、Postman或curl集成？

它们都是通过调用 http://localhost:11434 这个 API 地址来集成的。

• VSCode：有许多社区开发的 Ollama 插件（如 Continue），可以直接在编辑器里和本地模型对话。
• Postman / curl：直接向 /api/chat 或 /v1/chat/completions 端点发送 POST 请求即可，就像前文中的 curl 示例一样。

问：前端项目调用 Ollama API 跨域问题 (CORS)

在本地前端项目（如： http://localhost:8000）里调用 Ollama API （http://localhost:11434） 会因为跨域被拦截。你需要配置 Ollama 允许你的网页源访问，通过设置 OLLAMA_ORIGINS 环境变量来实现。在终端这样启动 Ollama 服务：OLLAMA_ORIGINS=* ollama serve 允许跨域。

如果Ollama是在macOS应用运行，也可以通过 launchctl 设置环境变量：

launchctl setenv OLLAMA_ORIGINS "*"

然后重启 Ollama 应用

---

这篇指南覆盖了前端开发者开始使用 Ollama 所需了解的核心知识。随着你的深入，你还可以探索更高级的主题，如 RAG (检索增强生成)、微调等。祝你玩得开心！