Ollama API 实用指南：10个技巧优化本地AI调试与REST API调用

如何在本地快速调试自己的AI应用？Ollama 这类工具提供了便捷的本地大模型运行环境，而其内置的 REST API 则是实现应用集成的关键。当你启动 Ollama 后，它会自动运行一个侦听端口 11434 的 REST API 服务，让你能够通过 HTTP 请求与模型进行交互，无论是查询、管理配置还是集成到其他应用程序中都十分方便。这对于构建需要统一访问 AI 能力的多语言应用栈尤其有用。想了解更多此类实践，可以到云栈社区的开发者板块交流讨论。

1. 使用 API 生成文本

要调用大模型生成文本，可以直接使用 curl 命令与 Ollama 的 API 端点通信：

$ curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Tell me a joke"
}'

以上命令指定使用 llama3.2 模型，并要求它讲一个笑话。注意，默认情况下响应是流式输出的，即模型会逐词生成结果。这种方式能降低延迟，为需要实时交互的应用提供更快的反馈，在处理长文本或优化低延迟场景时特别有用。

2. 禁用流式输出

虽然流式输出对实时交互有利，但有时我们更希望一次性获得完整响应。可以通过将 stream 参数设为 false 来关闭流式输出：

$ curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Tell me a joke", 
  "stream": false 
}'

3. 在 Python 中使用 Ollama API

借助 Python 的 requests 库，可以轻松地通过 HTTP 请求与 REST API 交互。下面的例子演示了如何发送 POST 请求让模型生成一个笑话：

import requests

url = "http://localhost:11434/api/generate"
model = "llama3.2" 

headers = {
    "Content-Type": "application/json",
}

data = {
    "model": model,
    "prompt": "Tell me a joke",
    "stream": False
}

response = requests.post(url, 
                         json = data,
                         headers = headers
                         )
print(response.json())

我们可以进一步从 API 响应中提取出我们需要的文本内容：

print(response.json()["response"])

4. 获取已安装模型列表

如果想查看当前服务器上已下载的模型列表，可以调用 /api/tags 端点：

import requests

url = "http://localhost:11434/api/tags"

response = requests.get(url)
print(response.json())

返回结果示例：

{
'models': [
{
'name': 'llama3.2:latest',
'model': 'llama3.2:latest',
'modified_at': '2025-06-20T09:19:47.514667577+08:00',
'size': 2019393189,
'digest': 'a80c4f17acd55265feec403c7aef86be0c25983ab279d83f3bcd3abbcb5b8b72',
'details': {
'parent_model': '',
'format': 'gguf',
'family': 'llama',
'families': ['llama'],
'parameter_size': '3.2B',
'quantization_level': 'Q4_K_M'
}
}
]
}

5. 获取特定模型的详细信息

要查看某个模型的详细配置信息，可以使用 /api/show 端点并在请求体中指定模型名称：

import requests

url = "http://localhost:11434/api/show"
headers = {
    "Content-Type": "application/json",
}
data = {
    "model": "llama3.2",
    "stream": False
}

response = requests.post(url, 
                         json = data,
                         headers = headers
                         )
print(response.json())

6. 生成文本嵌入向量

我们可以使用 /api/embed 端点来为输入的文本字符串生成嵌入向量：

import requests

url = "http://localhost:11434/api/embed"

headers = {
    "Content-Type": "application/json"   
}

data = {
    "model": "llama3.2",
    "input": "Generate embeddings for this text."
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

向量嵌入技术能让模型根据上下文捕捉词语间的语义关系，是许多自然语言处理任务（如相似性检测、聚类等）的基础。

7. 控制模型在内存中的驻留时间

默认情况下，Ollama 会在模型最后一次被使用后，将其在内存中保留 5 分钟。这平衡了频繁调用的响应速度与内存释放的需求。

如果希望立即从内存中卸载某个模型，可以使用 stop 命令：

$ ollama stop llama3.2

执行后，该模型将从内存中卸载。但后续若再次调用，它又会被重新加载。

如果希望模型永久驻留内存（不主动卸载），可以在调用时设置 keep_alive 参数为 -1（或任意负值）：

$ curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?", 
  "keep_alive": -1
}'

如何验证呢？使用 ollama ps 命令：

$ ollama ps
NAME               ID              SIZE      PROCESSOR    UNTIL   
llama3.2:latest    a80c4f17acd5    4.0 GB    100% GPU     Forever

输出显示 llama3.2 模型已完全加载至 GPU 内存，并将一直保留。

若希望请求结束后立即卸载模型，则将 keep_alive 设为 0。
如果希望模型在内存中保留指定时长，可以将 keep_alive 设为一个时间字符串，如 "24h"（24小时）或 "15m"（15分钟）：

$ curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Why is the sky blue?", 
  "keep_alive": "15m"
}'

此命令将使 llama3.2 模型在内存中驻留 15 分钟。

8. 更改模型存储目录

大模型体积庞大，动辄数GB甚至更大，默认存储在 ~/.ollama 目录可能会迅速占满主磁盘空间，尤其是在存储空间有限的设备上。

一个有效的解决方案是将所有模型转移到外部存储器，如外接 SSD 或硬盘。对于 Ollama，可以通过设置 OLLAMA_MODELS 环境变量来指定新的存储路径。以下命令将路径指向一个外接 SSD：

$ export OLLAMA_MODELS="/Volumes/MySSD/ollama"

设置环境变量后，需要退出并重启 Ollama，然后运行一个模型以使设置生效：

$ ollama run llama3.2
pulling manifest 
pulling dde5aa3fc5ff... 100% ▕████████████████▏ 2.0 GB                         
pulling 966de95ca8a6... 100% ▕████████████████▏ 1.4 KB                         
pulling fcc5a6bec9da... 100% ▕████████████████▏ 7.7 KB                         
pulling a70ff7e570d9... 100% ▕████████████████▏ 6.0 KB                         
pulling 56bb8bd477a5... 100% ▕████████████████▏   96 B                         
pulling 34bb5ab01051... 100% ▕████████████████▏  561 B                         
verifying sha256 digest 
writing manifest 
success

如果 llama3.2 模型不在新目录中，它将被下载并保存到指定位置。

请注意，在终端中直接 export 是临时生效的，系统重启后会失效。要永久设置，需要将 export 语句添加到 shell 配置文件中（如 .zshrc 或 .bash_profile），保存后执行 source ~/.zshrc 重新加载配置即可。

9. 更改 API 服务端口号

如果需要更改 Ollama REST API 的监听端口（默认为 11434），可以通过 OLLAMA_HOST 环境变量来配置：

$ export OLLAMA_HOST=127.0.0.1:8081

上面的命令将端口改为 8081。在终端中设置后，重启 Ollama 服务：

$ ollama serve

同样，若需永久生效，请将 export 语句添加到 shell 配置文件并重新加载。这有助于适应特定环境或避免端口冲突。

10. 在 Ollama 中使用 MCP

Model Context Protocol (MCP) 为AI应用连接工具和数据提供了标准化方式。配置 MCP 服务时，需要一个 JSON 文件来定义各个服务器。保存文件时需注意编码格式应为 UTF-8，以防乱码。下面是一个配置示例：

{
"globalShortcut": "Ctrl+Space",
"mcpServers": {
"sqlite": {
"command": "C:\\Users\\datas\\anaconda3\\Scripts\\uvx.exe",
"args": ["mcp-server-sqlite", "--db-path", "C:\\Users\\datas\\AI_Docs.db"]
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:\\Users\\datas\\OneDrive\\Desktop\\ollama-mcp"
]
}
}
}

安装好所需的 MCP server 后，可以使用以下命令启动服务（以Windows系统为例），并提供上面创建的配置文件路径：

mcphost -m ollama:qwen2.5 --config "C:\Users\datas\OneDrive\Desktop\local.json"

启动后，Ollama 就可以作为主机或客户端来使用配置好的 MCP 服务了。

小结

本文介绍了 Ollama 的几项实用配置技巧，包括如何通过环境变量将模型存储目录转移到外部存储以节省空间，以及如何使用 curl 和 Python 的 requests 库与 REST API 进行交互。我们还探讨了如何通过 keep_alive 参数精细控制模型在内存中的驻留时长，以及如何修改 API 服务的监听端口。最后，简要介绍了如何配置和使用 MCP 服务来扩展 Ollama 的能力。掌握这些技巧，能让你在本地 AI 应用开发和调试中更加得心应手。