快速掌握 Ollama API：本地部署与集成 – wiki基地

作者： /

快速掌握 Ollama API：本地部署与集成

在当前大型语言模型（LLM）飞速发展的时代，将强大的AI能力融入到我们自己的应用、服务或工作流程中已成为一种趋势。然而，对于许多开发者和组织而言，使用云端API服务可能面临数据隐私、成本、延迟或离线访问等挑战。这时，选择在本地部署和运行LLM就显得尤为重要。

Ollama 是一个应运而生的强大工具，它极大地简化了在本地机器上安装、管理和运行各种大型语言模型的过程。它不仅提供了一个简洁的命令行界面（CLI），更关键的是，它暴露了一组强大的、易于使用的 REST API，使得开发者能够轻松地将本地运行的LLMs集成到任何支持HTTP请求的应用中。

本文将详细探讨如何从零开始快速掌握 Ollama 的核心功能，特别是如何进行本地部署，以及如何通过其提供的 API 实现与各种应用的深度集成。我们将涵盖 Ollama 的安装、模型管理，并重点解析其主要的 API 端点，并通过实际的代码示例展示如何在不同的编程环境中调用这些 API。

第一部分：Ollama 基础与本地部署

在我们深入探讨 API 之前，首先需要搭建起 Ollama 的本地环境。

1. 理解 Ollama 是什么？

Ollama 是一个开源项目，旨在让用户能够在自己的计算机上轻松运行开源大型语言模型。它将模型的复杂性（如模型文件的下载、加载、硬件加速配置等）抽象化，提供一个统一的接口。你可以把它看作是一个本地的“模型商店”和“运行时”，通过它，你可以像管理Docker容器一样管理不同的LLM模型。

核心特性包括：

  • 简化的安装与运行： 一条命令即可下载并运行模型。
  • 广泛的模型支持： 支持 llama2, mistral, gemma, phi3 等众多流行开源模型，并持续增加。
  • API 接口： 提供标准的 REST API，便于集成。
  • Modelfile： 允许用户通过类似 Dockerfile 的方式定制或创建模型。
  • 硬件加速： 自动利用可用的GPU硬件（NVIDIA, AMD, Apple Silicon）来提高推理速度。

2. 为什么选择本地部署 Ollama？

  • 数据隐私与安全： 敏感数据无需发送到第三方云服务，完全在本地处理。
  • 成本效益： 一旦硬件投资到位，后续的使用成本远低于按使用量付费的云API。
  • 低延迟： 模型在本地运行，无需网络传输，响应速度更快。
  • 离线访问： 在没有互联网连接的环境下也能正常工作。
  • 定制与控制： 可以运行特定版本或自行微调的模型。
  • 实验与开发： 提供一个沙箱环境，方便开发者进行原型设计和实验。

3. Ollama 的本地安装

Ollama 支持 macOS、Windows 和 Linux 操作系统。安装过程通常非常简单。

通用步骤：

  1. 访问 Ollama 官方网站 (https://ollama.com/)。
  2. 点击下载按钮，选择适合你操作系统的版本。
  3. 按照官方提供的安装指南进行安装。

macOS: 下载并运行 .dmg 文件，将 Ollama 拖拽到应用程序文件夹。Ollama 会作为后台服务运行。

Windows: 下载并运行 .exe 安装程序，按照向导完成安装。安装完成后，Ollama 会作为后台服务运行。

Linux: 官方提供了各种发行版的安装脚本。打开终端，执行以下命令（可能需要 curl）：

bash
curl -fsSL https://ollama.com/install.sh | sh

这个脚本会检测你的系统并进行相应的安装。安装完成后，Ollama 服务会自动启动。

验证安装：

安装完成后，打开终端或命令提示符，运行：

bash
ollama --version

如果看到版本信息，说明 Ollama 已成功安装并运行。Ollama 服务默认会在 http://localhost:11434 监听 API 请求。

4. 下载和运行模型

安装 Ollama 后，你需要下载你想要使用的模型。Ollama CLI 提供了便捷的模型管理命令。

下载模型：

使用 ollama pull <model_name> 命令下载模型。你可以在 Ollama 官方网站的模型库 (https://ollama.com/library) 查看可用的模型列表。例如，下载 Llama 2 7B 模型：

bash
ollama pull llama2

或者下载 Mistral 7B 模型：

bash
ollama pull mistral

下载过程可能需要一些时间，具体取决于你的网络速度和模型大小。Ollama 会显示下载进度。

直接运行模型（CLI 交互）：

下载完成后，你可以直接使用 ollama run <model_name> 命令与模型进行交互：

bash
ollama run llama2

进入交互模式后，你可以输入你的提示词，模型会生成响应。按 Ctrl + D 或输入 /bye 退出交互模式。

“`bash

请问什么是生成式AI？
生成式AI是指能够创造新内容、新想法或新解决方案的机器学习模型和技术。它通常涉及训练模型从现有数据中学习模式、结构和风格，然后利用这些知识来生成新的、独特的输出。
… (模型响应) …
/bye
“`

这种方式非常适合快速测试模型或进行简单的交互。但对于程序化地使用模型，我们需要依赖 Ollama API。

列出已下载模型：

bash
ollama list

这个命令会显示所有已下载到本地的模型及其大小。

第二部分：深入解析 Ollama API

Ollama 的核心价值之一在于其提供的 REST API，它允许任何支持HTTP请求的程序与本地运行的LLM进行交互。Ollama API 默认在 http://localhost:11434 端口上运行。

接下来，我们将详细介绍 Ollama 的主要 API 端点。

API 基础

  • Base URL: http://localhost:11434
  • API Prefix: 所有 API 端点都以 /api/ 开头。
  • Request/Response Format: 主要使用 JSON 格式进行数据交换。
  • HTTP Methods: 主要使用 GET 和 POST。

核心 API 端点详解

1. 列出本地模型 (GET /api/tags)

这个端点用于获取当前 Ollama 实例中所有已下载并可用的模型列表。

  • Endpoint: GET /api/tags
  • Request Body: None
  • Response Body (JSON):

json
{
"models": [
{
"name": "llama2:latest",
"modified_at": "2023-11-20T10:38:20.748127337-07:00",
"size": 3826811656,
"digest": "78e26419b446928ba3613c62da0cddcd806327531906b9b9688735a5001661b7"
},
{
"name": "mistral:latest",
"modified_at": "2023-11-21T15:00:11.321457893-07:00",
"size": 4109852912,
"digest": "29a84415d5d6190d05865a65693b19f65d3b33cd20e3cb673b093176a9a1125e"
}
// ... more models
]
}

  • 解释:

    • models: 一个包含所有模型对象的数组。
    • name: 模型的全名（例如 llama2:latest）。
    • modified_at: 模型文件的最后修改时间。
    • size: 模型文件的大小（字节）。
    • digest: 模型的唯一标识符。

  • 用途: 在应用程序中动态获取可用模型列表，例如填充下拉菜单或进行模型选择。

2. 文本生成 (POST /api/generate)

这是最常用的端点之一，用于接收一个提示词并生成文本响应。它适用于各种文本生成任务，如补全、摘要、翻译等。

  • Endpoint: POST /api/generate
  • Request Body (JSON):

json
{
"model": "llama2", // 必需，要使用的模型名称
"prompt": "Why is the sky blue?", // 必需，输入提示词
"system": "You are a helpful assistant.", // 可选，系统消息，设定模型的角色或行为
"template": "...", // 可选，使用自定义提示模板覆盖模型默认模板
"context": [...], // 可选，用于无状态API的上下文信息（详见下文）
"options": { // 可选，控制生成过程的参数
"temperature": 0.8, // 生成文本的随机性 (0.0 - 2.0)
"top_k": 40, // 限制采样时只考虑概率最高的k个词
"top_p": 0.9, // 限制采样时只考虑累计概率达到p的词集
"num_predict": 1024, // 最大生成token数
"repeat_penalty": 1.1, // 重复惩罚因子
// ... 更多参数，参考Ollama文档
},
"stream": false, // 是否流式返回结果 (true/false, 默认为false)
"raw": false // 是否跳过模型内部的提示词处理，直接使用prompt作为输入
}

  • 主要参数解释:

    • model: 必需，指定使用哪个模型进行生成。
    • prompt: 必需，用户的主要输入提示词。
    • system: 可选，提供给模型的系统级别指令，帮助模型理解其角色或限制其输出风格。
    • options: 包含各种控制模型生成行为的参数。这些参数对生成文本的创造性、连贯性等方面有重要影响。
      • temperature: 越高，输出越随机、有创意；越低，输出越确定、保守。
      • top_k, top_p: 控制采样范围，影响输出的多样性。
      • num_predict: 控制生成文本的最大长度。
    • stream: 如果设置为 true，API 会以流的形式逐个或逐批返回生成的token，而不是等待整个生成过程完成。这对于实时显示模型输出非常有用，尤其是在构建聊天应用时。
    • context: 这个参数比较特殊。generate API 本身是无状态的，如果你想进行多轮对话，需要在每次请求时手动维护并传入上一次对话的上下文。Ollama 在响应中会返回一个 context 数组，你需要在下一次请求时将其包含在 context 参数中。但这通常不如 chat API方便。

  • Response Body (JSON, stream: false):

json
{
"model": "llama2:latest",
"created_at": "2023-11-21T15:31:54.45779494-07:00",
"response": "The sky appears blue because of a phenomenon called Rayleigh scattering. Sunlight ...", // 生成的完整文本
"done": true, // 是否生成完成
"context": [...] // 下一次请求时需要包含的上下文信息
}

  • Response Body (JSON Stream, stream: true):
    API 会返回一系列 JSON 对象，每个对象代表一部分生成的文本或状态信息。

json
{
"model": "llama2:latest",
"created_at": "2023-11-21T15:33:01.18641476-07:00",
"response": "The",
"done": false // 未完成
}
{
"model": "llama2:latest",
"created_at": "2023-11-21T15:33:01.28641476-07:00",
"response": " sky",
"done": false
}
// ... 更多响应块
{
"model": "llama2:latest",
"created_at": "2023-11-21T15:33:05.45779494-07:00",
"response": "", // 最后一个块可能response为空
"done": true, // 完成标记
"context": [...] // 完整的上下文
}

  • 用途: 实现各种非对话式的文本处理功能，或在需要手动控制对话状态的场景下使用。
3. 聊天式生成 (POST /api/chat)

这个端点是 Ollama 推荐用于构建聊天应用的 API。它原生支持多轮对话的状态管理，通过传递一个包含消息历史的数组来实现。

  • Endpoint: POST /api/chat
  • Request Body (JSON):

json
{
"model": "mistral", // 必需，要使用的模型名称
"messages": [ // 必需，消息历史数组
{ "role": "system", "content": "You are a helpful assistant that speaks like a pirate." }, // 系统消息 (可选)
{ "role": "user", "content": "Tell me a story." }, // 用户消息
{ "role": "assistant", "content": "Ahoy there, matey! Let me spin ye a yarn..." }, // 助手消息 (可选，来自模型的上一次响应)
{ "role": "user", "content": "Tell me another one, but make it shorter." } // 当前用户消息
],
"options": { // 可选，控制生成过程的参数 (同 generate API)
"temperature": 0.7,
"top_p": 0.9
},
"stream": false // 是否流式返回结果 (true/false, 默认为false)
}

  • 主要参数解释:

    • model: 必需，指定使用的模型。
    • messages: 必需，一个包含消息对象的数组。每个消息对象必须有 role (system, user, assistant) 和 content 字段。传递整个对话历史（除了模型上一次响应的最后一个 assistant 消息，新的响应将接续它）是实现多轮对话的关键。
    • options: 同 generate API，用于调整生成参数。
    • stream: 同 generate API，控制是否流式返回。

  • Response Body (JSON, stream: false):

json
{
"model": "mistral:latest",
"created_at": "2023-11-21T15:40:33.45779494-07:00",
"message": { // 生成的助手消息
"role": "assistant",
"content": "Arr, listen closely, and I'll tell ye a tale..."
},
"done": true, // 是否生成完成
"total_duration": 123456789, // 总耗时 (ns)
"load_duration": 1234567, // 模型加载耗时 (ns)
"prompt_eval_count": 123, // 提示词token数
"prompt_eval_duration": 1234567, // 提示词评估耗时 (ns)
"eval_count": 45, // 生成token数
"eval_duration": 7891011, // 生成耗时 (ns)
}

  • Response Body (JSON Stream, stream: true):
    与 generate 流相似，但每个块包含一个 message 对象，其中 content 字段包含增量的文本。

json
{
"model": "mistral:latest",
"created_at": "2023-11-21T15:42:01.18641476-07:00",
"message": {
"role": "assistant",
"content": "Arr,"
},
"done": false
}
{
"model": "mistral:latest",
"created_at": "2023-11-21T15:42:01.28641476-07:00",
"message": {
"role": "assistant",
"content": " listen"
},
"done": false
}
// ... 更多响应块
{
"model": "mistral:latest",
"created_at": "2023-15:42:05.45779494-07:00",
"message": {
"role": "assistant",
"content": ""
},
"done": true, // 完成标记
// 包含性能指标 total_duration 等...
}

  • 用途: 构建聊天机器人、虚拟助手或其他需要维护多轮对话状态的应用。这是推荐用于对话场景的 API。
4. 生成嵌入向量 (POST /api/embeddings)

这个端点用于获取输入文本的嵌入向量（Embedding）。嵌入向量是文本的数值表示，捕捉了文本的语义信息，常用于搜索、聚类、相似度计算等任务。

  • Endpoint: POST /api/embeddings
  • Request Body (JSON):

json
{
"model": "nomic-embed-text", // 必需，通常使用专门的嵌入模型
"prompt": "The quick brown fox jumps over the lazy dog." // 必需，要生成嵌入的文本
}

  • 注意: 生成高质量的嵌入向量需要使用专门训练用于此任务的模型。Ollama 模型库中提供了如 nomic-embed-text 或 all-minilm 等模型。确保你已经 ollama pull 了这些模型。

  • Response Body (JSON):

json
{
"embedding": [ // 嵌入向量数组
0.123456,
-0.789012,
... // (向量的维度取决于模型)
0.345678
]
}

  • 用途: 构建基于语义的搜索系统（RAG – Retrieval Augmented Generation 的一部分）、文本相似度比较、文本分类预处理等。
5. 创建模型 (POST /api/create)

这个端点允许你使用一个 Modelfile 来创建一个新的模型或者定制现有模型。Modelfile 定义了模型的配置、基础模型、以及如何处理输入和输出（例如添加系统提示词、自定义模板）。

  • Endpoint: POST /api/create
  • Request Body (JSON):

json
{
"name": "my-custom-model", // 必需，新模型的名称
"modelfile": "FROM llama2\nSYSTEM You are a helpful, polite assistant.", // 必需，Modelfile 内容字符串
"stream": false // 是否流式返回创建过程的日志
}

  • Modelfile 示例 (modelfile 字段内容):

“`modelfile

基于 llama2 模型

FROM llama2

设置系统消息，定义模型的角色

SYSTEM “””
你是一个友善且乐于助人的中文AI助手。
请用简洁明了的中文回答问题。
“””

设置一些生成参数的默认值

PARAMETER temperature 0.8
PARAMETER top_k 40
PARAMETER top_p 0.9

定义聊天模板 (可选，如果基础模型自带聊天模板通常不需要)

TEMPLATE “””{{ if .System }}<|system|>{{ .System }}<|end|>{{ end }}{{ if .Prompt }}<|user|>{{ .Prompt }}<|end|>{{ end }}<|assistant|>”””

“`

  • 用途: 创建带有特定系统指令、参数配置或提示模板的定制模型，以便更方便地在 API 调用中使用。
6. 删除模型 (DELETE /api/delete)

通过模型的名称删除本地的模型文件。

  • Endpoint: DELETE /api/delete
  • Request Body (JSON):

json
{
"model": "my-custom-model" // 必需，要删除的模型名称
}

  • Response: 通常返回 200 OK 状态码表示成功，或 404 Not Found 如果模型不存在。

  • 用途: 释放磁盘空间，移除不再需要的模型。

7. 复制模型 (POST /api/copy)

复制一个现有模型到新的名称。这在你想要基于一个模型进行实验或创建变体时很有用。

  • Endpoint: POST /api/copy
  • Request Body (JSON):

json
{
"source": "llama2", // 必需，源模型名称
"destination": "llama2-copy" // 必需，目标模型名称
}

  • Response: 通常返回 200 OK 状态码表示成功。

  • 用途: 快速创建模型副本，例如在测试不同的 Modelfile 时保留原始模型。

8. 拉取模型 (POST /api/pull)

通过 API 拉取模型到本地。这与 CLI 的 ollama pull 功能相同。

  • Endpoint: POST /api/pull
  • Request Body (JSON):

json
{
"name": "gemma:2b", // 必需，要拉取的模型名称
"insecure": false, // 可选，是否允许不安全的HTTPS连接 (通常不需要)
"stream": true // 可选，是否流式返回进度 (默认为false)
}

  • Response: 如果 stream 为 true，会流式返回拉取进度信息。如果 stream 为 false，会在拉取完成后返回一个包含最终状态的 JSON 对象。

  • 用途: 在应用程序启动时或需要时动态下载模型。

9. 推送模型 (POST /api/push)

将本地创建或修改的模型推送到 Ollama Registry 或其他兼容的 Registry。这对于分享你定制的模型非常有用。

  • Endpoint: POST /api/push
  • Request Body (JSON):

json
{
"name": "myuser/my-custom-model:latest", // 必需，要推送的模型名称 (格式通常为 用户名/模型名:标签)
"insecure": false, // 可选，是否允许不安全的HTTPS连接
"stream": true // 可选，是否流式返回进度 (默认为false)
}

  • 注意: 推送需要注册并登录到 Ollama Registry 或你使用的其他 Registry。

  • 用途: 分享定制模型，构建团队内部的模型库。

第三部分：集成 Ollama API 到应用

掌握了 API 端点的功能后，下一步就是如何在实际的编程语言中调用这些 API，将本地LLMs的能力融入你的应用程序。这里我们以 Python 和 JavaScript (Node.js) 为例。

1. 使用 Python 集成 Ollama API

Python 是一个广泛用于AI/ML开发的语言，有多种方式可以调用 Ollama API。

方法一：使用 requests 库 (低层级 HTTP 请求)

这种方法直接构建 HTTP 请求，适合理解 API 底层工作原理。

首先，安装 requests 库：

bash
pip install requests

示例：调用 /api/generate (非流式)

“`python
import requests
import json

ollama_url = “http://localhost:11434/api/generate”

prompt_text = “What is the capital of France?”
model_name = “llama2” # 确保你已经下载了这个模型

payload = {
“model”: model_name,
“prompt”: prompt_text,
“stream”: False # 非流式
}

try:
response = requests.post(ollama_url, json=payload)
response.raise_for_status() # 检查请求是否成功 (状态码 2xx)

result = response.json()
print("Generated Text:")
print(result.get("response", "No response generated."))

except requests.exceptions.RequestException as e:
print(f”Error calling Ollama API: {e}”)
print(“Please ensure Ollama is running and the model is available.”)

“`

示例：调用 /api/chat (流式)

流式请求需要特别处理响应，因为数据会分块返回。

“`python
import requests
import json

ollama_chat_url = “http://localhost:11434/api/chat”

messages = [
{“role”: “system”, “content”: “You are a friendly AI assistant.”},
{“role”: “user”, “content”: “Tell me a short story about a cat.”}
]
model_name = “mistral” # 确保你已经下载了这个模型

payload = {
“model”: model_name,
“messages”: messages,
“stream”: True # 开启流式
}

try:
print(“Generated Text (Streaming):”)
with requests.post(ollama_chat_url, json=payload, stream=True) as r:
r.raise_for_status() # 检查请求是否成功

    for line in r.iter_lines():
        if line:
            try:
                # 每行是一个JSON对象，需要解析
                data = json.loads(line)
                # 从流式响应中提取内容
                if "message" in data and "content" in data["message"]:
                     print(data["message"]["content"], end="", flush=True) # end="" 避免换行, flush=True 实时显示
                if data.get("done", False):
                    break # 生成完成
            except json.JSONDecodeError:
                print("\nError decoding JSON line:", line)
            except Exception as e:
                 print(f"\nError processing stream line: {e}")

print("\n--- Generation Complete ---")

except requests.exceptions.RequestException as e:
print(f”Error calling Ollama API: {e}”)
print(“Please ensure Ollama is running and the model is available.”)

“`

方法二：使用官方 ollama-python 库 (高层级抽象)

Ollama 社区提供了官方的 Python 客户端库，它封装了底层的 HTTP 请求，提供了更简洁易用的接口。

首先，安装库：

bash
pip install ollama

示例：使用 ollama-python 调用 generate

“`python
import ollama

prompt_text = “Write a short poem about nature.”
model_name = “llama2” # 确保模型已下载

try:
response = ollama.generate(model=model_name, prompt=prompt_text)
print(“Generated Text:”)
print(response[‘response’])

except ollama.ResponseError as e:
print(f”Error calling Ollama: {e}”)
print(“Please ensure Ollama is running and the model is available.”)

“`

示例：使用 ollama-python 调用 chat (非流式)

“`python
import ollama

messages = [
{‘role’: ‘user’, ‘content’: ‘What is the capital of Japan?’},
]
model_name = “mistral” # 确保模型已下载

try:
response = ollama.chat(model=model_name, messages=messages)
print(“Generated Message:”)
print(response[‘message’][‘content’])

except ollama.ResponseError as e:
print(f”Error calling Ollama: {e}”)
print(“Please ensure Ollama is running and the model is available.”)

“`

示例：使用 ollama-python 调用 chat (流式)

流式处理在 ollama-python 库中也非常直观。

“`python
import ollama

messages = [
{‘role’: ‘system’, ‘content’: ‘You are a concise and helpful assistant.’},
{‘role’: ‘user’, ‘content’: ‘Explain quantum computing in simple terms.’},
]
model_name = “mistral” # 确保模型已下载

try:
print(“Generated Text (Streaming):”)
stream = ollama.chat(model=model_name, messages=messages, stream=True)
for chunk in stream:
if “message” in chunk and “content” in chunk[“message”]:
print(chunk[‘message’][‘content’], end=”, flush=True)

print("\n--- Generation Complete ---")

except ollama.ResponseError as e:
print(f”Error calling Ollama: {e}”)
print(“Please ensure Ollama is running and the model is available.”)

“`

示例：使用 ollama-python 调用 embeddings

“`python
import ollama

text_to_embed = “Hello, world!”
model_name = “nomic-embed-text” # 确保嵌入模型已下载

try:
response = ollama.embeddings(model=model_name, prompt=text_to_embed)
print(“Embedding Vector:”)
print(response[’embedding’][:10], “…”) # 打印前10个元素作为示例

except ollama.ResponseError as e:
print(f”Error calling Ollama: {e}”)
print(“Please ensure Ollama is running and the model is available.”)
print(“Also, make sure you are using an appropriate embedding model.”)

“`

总结 Python 集成： 对于大多数应用场景，推荐使用官方 ollama-python 库，它提供了更高级别的抽象，简化了 API 调用和流式处理。

2. 使用 JavaScript (Node.js) 集成 Ollama API

在 Node.js 环境中，你可以使用内置的 fetch API (Node.js v18+) 或第三方库如 axios 来调用 Ollama API。社区也提供了 @ollama/sdk。

首先，确保你的 Node.js 版本支持 fetch 或安装 axios / @ollama/sdk：

“`bash

如果使用 fetch (Node.js v18+) 无需安装

如果使用 axios

npm install axios

如果使用官方 SDK

npm install @ollama/sdk

或者使用 Langchain 社区适配器 (更推荐用于 Langchain 项目)

npm install @langchain/community

“`

方法一：使用 fetch 或 axios (低层级 HTTP 请求)

示例：使用 fetch 调用 /api/generate (非流式)

“`javascript
// Requires Node.js v18+

const ollamaUrl = “http://localhost:11434/api/generate”;

async function generateText(modelName, promptText) {
try {
const response = await fetch(ollamaUrl, {
method: ‘POST’,
headers: {
‘Content-Type’: ‘application/json’
},
body: JSON.stringify({
model: modelName,
prompt: promptText,
stream: false
})
});

if (!response.ok) {
  const errorText = await response.text();
  throw new Error(`HTTP error! status: ${response.status}, message: ${errorText}`);
}

const data = await response.json();
console.log("Generated Text:");
console.log(data.response || "No response generated.");

} catch (error) {
console.error(“Error calling Ollama API:”, error);
console.error(“Please ensure Ollama is running and the model is available.”);
}
}

generateText(“llama2”, “Write a simple greeting.”); // 确保模型已下载
“`

示例：使用 fetch 调用 /api/chat (流式)

处理流式响应需要使用 response.body.getReader()。

“`javascript
// Requires Node.js v18+

const ollamaChatUrl = “http://localhost:11434/api/chat”;

async function chatWithModel(modelName, messages) {
try {
const response = await fetch(ollamaChatUrl, {
method: ‘POST’,
headers: {
‘Content-Type’: ‘application/json’
},
body: JSON.stringify({
model: modelName,
messages: messages,
stream: true // 开启流式
})
});

if (!response.ok) {
  const errorText = await response.text();
   throw new Error(`HTTP error! status: ${response.status}, message: ${errorText}`);
}

console.log("Generated Text (Streaming):");
const reader = response.body.getReader();
const decoder = new TextDecoder(); // 用于解码Uint8Array到字符串

while (true) {
  const { value, done } = await reader.read();
  if (done) break;

  // 每个 value 是一个 Uint8Array，可能包含多个 JSON 对象或不完整的 JSON
  // 在 Node.js 中通常每行一个 JSON 对象，但在某些情况下需要更复杂的解析
  const chunk = decoder.decode(value, { stream: true }); // decode streamingly

  // 简单的按行分割解析 (对于 Ollama 的 stream 响应通常可行)
  const jsonLines = chunk.split('\n').filter(line => line.trim() !== '');

  for (const line of jsonLines) {
      try {
          const data = JSON.parse(line);
          if (data.message && data.message.content) {
              process.stdout.write(data.message.content); // 实时输出不换行
          }
          if (data.done) {
              // console.log("\n--- Generation Complete ---"); // 可选的完成标记
              reader.cancel(); // 提前结束读取
              return; // 退出函数
          }
      } catch (e) {
          console.error("\nError parsing JSON chunk:", line, e);
      }
  }
}
 console.log("\n--- Generation Complete ---"); // 如果不是通过 data.done 退出循环

} catch (error) {
console.error(“Error calling Ollama API:”, error);
console.error(“Please ensure Ollama is running and the model is available.”);
}
}

const chatMessages = [
{ role: “user”, content: “Tell me about the history of the internet.” }
];
chatWithModel(“mistral”, chatMessages); // 确保模型已下载
“`

方法二：使用官方 @ollama/sdk 或 @langchain/community 库 (高层级抽象)

使用 SDK 可以进一步简化代码。

示例：使用 @ollama/sdk 调用 chat

“`javascript
import ollama from ‘@ollama/sdk’;

// 创建客户端实例 (可选，如果不指定URL默认是 http://localhost:11434)
const client = new ollama();

async function chatWithOllamaSDK(modelName, messages) {
try {
console.log(“Generated Text (Streaming via SDK):”);
const stream = await client.chat({
model: modelName,
messages: messages,
stream: true,
});

    for await (const part of stream) {
        if (part.message && part.message.content) {
            process.stdout.write(part.message.content);
        }
    }
    console.log("\n--- Generation Complete ---");

} catch (error) {
     console.error("Error calling Ollama SDK:", error);
     console.error("Please ensure Ollama is running and the model is available.");
}

}

const chatMessagesSDK = [
{ role: “system”, content: “You are a helpful coding assistant.” },
{ role: “user”, content: “Write a simple Python function to calculate Fibonacci sequence.” }
];
chatWithOllamaSDK(“mistral”, chatMessagesSDK); // 确保模型已下载
“`

示例：使用 @ollama/sdk 调用 embeddings

“`javascript
import ollama from ‘@ollama/sdk’;

const client = new ollama();

async function getEmbeddings(modelName, text) {
try {
const response = await client.embeddings({
model: modelName,
prompt: text,
});

    console.log("Embedding Vector (first 10 elements):");
    console.log(response.embedding.slice(0, 10));

} catch (error) {
     console.error("Error calling Ollama SDK:", error);
     console.error("Please ensure Ollama is running and the embedding model is available.");
}

}

getEmbeddings(“nomic-embed-text”, “Artificial Intelligence is transforming industries.”); // 确保嵌入模型已下载
“`

总结 JavaScript 集成： 对于 Node.js 项目，推荐使用 @ollama/sdk 或集成到 Langchain/LlamaIndex 等框架时使用对应的 Ollama 适配器 (@langchain/community)，它们提供了更便捷的异步操作和流式处理能力。

第四部分：高级主题与最佳实践

掌握了基础部署和 API 调用后，可以进一步探索 Ollama 的高级功能和使用技巧。

1. 硬件考量与性能优化

本地运行 LLM 对硬件有一定要求，尤其是显卡（GPU）。

  • GPU (显卡): 这是影响 LLM 推理速度最重要的硬件。Ollama 可以利用 NVIDIA (通过 CUDA)、AMD (通过 ROCm) 和 Apple Silicon (通过 Metal) 的 GPU 进行加速。模型的参数量越大，所需的显存 (VRAM) 就越多。例如，一个 7B 参数的模型通常需要 8GB 左右的 VRAM。如果显存不足，Ollama 会尝试使用 CPU 内存，但这会显著降低推理速度。
  • RAM (内存): 除了 VRAM，系统内存也很重要，特别是在显存不足或运行较大模型时。建议至少 16GB，推荐 32GB 或更多。
  • CPU (处理器): 虽然 GPU 是瓶颈，但一个较好的 CPU 也能提升整体体验，尤其是在加载模型或处理非计算密集型任务时。

性能优化技巧：

  • 选择合适的模型大小： 根据你的硬件能力选择参数量较小的模型（如 7B, 3B）进行初步测试。
  • 模型量化 (Quantization): Ollama 库中提供了不同量化等级的模型（例如 model_name:7b-q4_0）。量化模型使用较低精度的数据类型存储参数，可以显著减小模型体积并降低显存/内存需求，同时保持相对不错的性能。选择适合你硬件的量化版本。
  • 确保 GPU 加速启用： 检查 Ollama 的日志输出，确认它是否成功检测到并使用了你的 GPU。如果遇到问题，检查显卡驱动是否正确安装。
  • 批量处理 (Batching): 如果你的应用需要同时处理多个提示词，可以考虑使用支持批量处理的框架或自定义逻辑来提高GPU利用率（尽管 Ollama 的原生 API 尚未直接暴露批量接口，但这在构建上层应用时是需要考虑的）。

2. 使用 Modelfile 定制模型

Modelfile 是 Ollama 中非常强大的功能，它允许你：

  • 基于一个现有的模型。
  • 添加或修改模型的系统指令 (SYSTEM)。
  • 调整模型的默认参数 (PARAMETER)。
  • 定义自定义的聊天模板 (TEMPLATE)。
  • 甚至通过 ADAPTER 加载 LoRA 适配器进行微调。

例如，你可以创建一个 Modelfile，让 Llama 2 总是用 JSON 格式回答问题：

“`modelfile
FROM llama2

SYSTEM “””
You are a helpful assistant that responds only in JSON format.
Do not include any prose or explanations outside the JSON.
“””

PARAMETER temperature 0.7
PARAMETER top_k 40
PARAMETER top_p 0.9
“`

然后使用 ollama create my-json-llama -f ./Modelfile 命令创建模型，并通过 API 调用 my-json-llama 模型，它就会遵循你在 Modelfile 中设定的行为。

通过 API 的 /api/create 端点，你也可以在应用程序中动态创建模型。

3. 错误处理与调试

调用 API 时可能会遇到各种问题：

  • 连接错误： Ollama 服务未运行，防火墙阻止连接，或端口冲突。确保 Ollama 正在运行，监听在 http://localhost:11434，并且该端口没有被其他程序占用。
  • 模型未找到 (404 Not Found)： 你请求的模型名称不正确，或者该模型尚未通过 ollama pull 下载到本地。
  • 内部服务器错误 (500 Internal Server Error)： 模型加载失败、显存不足、输入格式问题或模型推理过程中发生其他错误。查看 Ollama 的日志输出可以帮助诊断问题（在 macOS/Windows 上查看应用日志，在 Linux 上查看 systemd 或其他服务管理器的日志）。
  • 请求格式错误 (400 Bad Request)： 你的请求 JSON 格式不正确，缺少必需参数，或者参数值无效。仔细检查 API 文档和你的请求体。

在代码中实现健壮的错误处理（如 try...except 或 try...catch 块）和对 API 响应状态码的检查至关重要。

4. 安全性考量

默认情况下，Ollama API 只监听 localhost (127.0.0.1)，这意味着它只能从同一台机器访问，这在大多数本地开发和个人使用场景下是安全的。

警告： 如果你修改了 Ollama 的配置使其监听外部 IP 地址（例如 0.0.0.0），请务必了解潜在的安全风险！任何能够访问该 IP 和端口的人都可能调用你的 Ollama API，消耗你的计算资源或与模型进行交互。除非你有明确的需求并采取了适当的安全措施（如防火墙规则、API 密钥等），否则不要将 Ollama API 暴露到本地网络或公共互联网上。

结论

Ollama 为在本地运行大型语言模型提供了一个极其便捷的解决方案，而其提供的 REST API 则是将这些本地能力融入到更广泛应用程序中的关键。通过本文的详细介绍，你已经掌握了 Ollama 的本地部署方法、核心 API 端点的功能及用法，并通过 Python 和 JavaScript 的代码示例了解了如何在实际项目中调用这些 API。

从简单的文本生成到复杂的聊天机器人和语义搜索，Ollama API 为开发者打开了本地 LLM 应用的大门。通过结合 Ollama 的 Modelfile 功能，你还可以进一步定制模型，使其更好地服务于你的特定需求。

快速掌握 Ollama API，意味着你可以在保证数据隐私、控制成本和降低延迟的同时，充分利用开源 LLM 的强大能力，构建下一代智能应用。现在，就开始你的实践，探索更多可能性吧！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部