📖 前言

随着大语言模型的快速发展，如何在本地高效部署和调用模型成为开发者关注的重点。Ollama作为一个轻量级的本地LLM运行框架，提供了简洁而强大的REST API接口，让我们能够轻松实现模型的程序化调用。本文将深入解析Ollama REST API的核心功能和实际应用。

---

1. Ollama API 概述

🎯 什么是Ollama REST API？

Ollama提供的核心REST API端点包括：

POST /api/generate：用于生成文本响应（流式端点）、

POST /api/chat：用于对话交互，以及其他辅助端点用于模型管理。

🔧 主要功能特性

• 🚄 高性能：本地化部署，响应速度快
• 🔒 数据安全：无需上传数据到云端，保护隐私
• ⚡ 简单易用：标准HTTP接口，支持多种编程语言
• 🔄 流式响应：支持实时文本生成
• 🛠️ 灵活配置：丰富的参数控制选项

---

2. 核心端点详解

📡 主要API端点

端点	方法	功能描述
/api/generate	POST	文本生成（核心功能）
/api/chat	POST	对话交互
/api/tags	POST	获取模型列表
/api/show	POST	显示模型信息
/api/pull	POST	下载模型
/api/push	POST	推送模型
/api/create	POST	创建模型
/api/delete	DELETE	删除模型

---

3. /api/generate 接口深度解析

🔧 必需参数

参数名	类型	描述
model	string	模型名称（格式：model:tag，默认latest）
prompt	string	生成响应的提示文本

⚙️ 可选参数配置

基础参数

{
  "model": "deepseek-r1:32b",
  "prompt": "请介绍一下人工智能",
  "suffix": "谢谢！",
  "format": "json",
  "stream": false,
  "system": "你是一个专业的AI助手"
}

高级options参数

options参数是模型参数集合（如温度、上下文窗口等），主要包括：

参数	类型	默认值	描述
temperature	float	0.8	生成随机性（值越高越具创造性）
num_ctx	int	2048	上下文窗口大小（影响模型记忆的最大token数）
num_predict	int	-1	最大生成token数（默认-1，无限生成）
stop	string	-	停止生成的触发序列

---

4. 实战案例演示

🔧 前置条件检查

Step 1: 启动Ollama服务

软件安装

1. 安装Ollama

# Windows
直接下载安装包：https://ollama.com/download

# macOS
brew install ollama

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

#Docker部署：
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

2. 验证安装

ollama --version
# 输出示例：ollama version is 0.1.44

3. 安装Python依赖

pip install requests json

 4. 下载模型

# 推荐几个轻量级模型（选择一个即可）
ollama pull llama3.2:3b       # 3B参数，约2GB
ollama pull qwen2.5:7b        # 7B参数，约4GB  
ollama pull gemma2:2b         # 2B参数，约1.5GB
ollama pull gemma3:1b         # 2B参数，约815 MB
# 查看已安装的模型
ollama list

输出示例：
NAME              ID              SIZE      MODIFIED
llama3.2:3b       a6990ed6be41    2.0 GB    2 minutes ago
qwen2.5:7b        845dbda0ea48    4.7 GB    5 minutes ago

5. 启动模型

ollama run gemma3:1b 

 6. 测试API连通性

# 方法1：使用curl测试
curl http://localhost:11434/api/tags

# 方法2：浏览器访问
# 打开浏览器，访问：http://localhost:11434

💻 完整代码示例

创建一个名为 ollama_api_test.py 的文件：

import requests
import json

def test_ollama_api():
    """测试Ollama API基础调用"""
    
    # 1. 配置API端点
    generate_url = "http://localhost:11434/api/generate"
    
    # 2. 准备请求数据
    payload = {
        "model": "gemma3:1b",  # 替换成已下载的模型
        "prompt": "请介绍一下机器学习的基本概念",
        "stream": False,  # 非流式，获取完整响应
        "options": {
            "temperature": 0.6,    # 控制随机性
            "num_ctx": 4096,       # 上下文窗口大小
            "num_predict": 500     # 最大生成token数
        }
    }
    
    print("🚀 正在调用Ollama API...")
    print(f"📡 请求URL: {generate_url}")
    print(f"🤖 使用模型: {payload['model']}")
    print(f"❓ 提问: {payload['prompt']}")
    print("-" * 50)
    
    try:
        # 3. 发送POST请求
        response = requests.post(generate_url, json=payload, timeout=60)
        
        # 4. 检查响应状态
        if response.status_code == 200:
            result = response.json()
            
            # 5. 输出结果
            print("✅ API调用成功！")
            print(f"🤖 AI回复: {result['response']}")
            print("-" * 50)
            
            # 6. 显示性能指标
            print("📊 性能指标:")
            if 'total_duration' in result:
                print(f"   ⏱️  总耗时: {result['total_duration'] / 1e9:.2f} 秒")
            if 'load_duration' in result:
                print(f"   📥 加载时间: {result['load_duration'] / 1e9:.2f} 秒")
            if 'prompt_eval_count' in result:
                print(f"   📝 输入tokens: {result['prompt_eval_count']}")
            if 'eval_count' in result:
                print(f"   💬 输出tokens: {result['eval_count']}")
            
            return result
            
        else:
            print(f"❌ API调用失败，状态码: {response.status_code}")
            print(f"📄 错误信息: {response.text}")
            return None
            
    except requests.exceptions.ConnectionError:
        print("❌ 连接失败！请确认：")
        print("   1. Ollama服务是否已启动（运行: ollama serve）")
        print("   2. 端口11434是否可访问")
        return None
        
    except requests.exceptions.Timeout:
        print("⏰ 请求超时！可能原因：")
        print("   1. 模型较大，生成时间较长")
        print("   2. 系统资源不足")
        return None
        
    except Exception as e:
        print(f"❌ 发生错误: {str(e)}")
        return None

if __name__ == "__main__":
    # 执行测试
    result = test_ollama_api()
    
    if result:
        print("\n🎉 测试完成！代码执行成功！")
    else:
        print("\n💡 如需帮助，请检查上述提示信息")

---

🎯 详细执行步骤

Step 1: 创建Python文件

1. 打开任意文本编辑器（VS Code、PyCharm、记事本等）
2. 复制上面的完整代码
3. 保存为 ollama_api_test.py
4. 在终端执行命令：python ollama_api_test.py

💻 基础调用示例

import requests
import json

# 配置API端点
generate_url = "http://localhost:11434/api/generate"

# 基础请求
payload = {
    "model": "gemma3:1b",  # 确保这个模型已下载
    "prompt": "请介绍一下机器学习的基本概念",
    "stream": False,
    "options": {
        "temperature": 0.6,
        "num_ctx": 4096,
        "num_predict": 500
    }
}

response = requests.post(generate_url, json=payload)
if response.status_code == 200:
    result = response.json()
    print("AI回复:", result["response"])
    print("处理时间:", result.get("total_duration", 0) / 1e9, "秒")
else:
    print("请求失败，状态码:", response.status_code)
    print("错误信息:", response.text)

🌊 流式响应处理

from ollama import chat
from ollama import ChatResponse

response: ChatResponse = chat(model='gemma3:1b', messages=[
  {
    'role': 'user',
    'content': '为什么天空是蓝色的？',
  },
])
print(response['message']['content'])

print(response.message.content)

5. 高级特性与优化

🔧 性能优化技巧

1. 合理设置上下文窗口

# 根据任务类型调整上下文大小
short_task_options = {"num_ctx": 2048}    # 短文本任务
long_task_options = {"num_ctx": 8192}     # 长文档处理

2. 模型生命周期管理

keep_alive参数控制模型在请求后保持加载的时间（默认5分钟，支持m/h/s单位或负数永久加载）

# 长时间使用，保持模型加载
payload["keep_alive"] = "30m"  # 30分钟
# 永久保持
payload["keep_alive"] = -1

3. 响应格式控制

# 确保JSON格式输出
payload["format"] = "json"
payload["system"] = "请以JSON格式回复，确保格式正确"

📊 性能监控

def analyze_response(response):
    result = response.json()
    """分析API响应性能"""
    metrics = {
        "总耗时": f"   ⏱️  总耗时: {result['total_duration'] / 1e9:.2f} 秒",
        "加载时间": f"   📥 加载时间: {result['load_duration'] / 1e9:.2f} 秒",
        "输入tokens": f"   📝 输入tokens: {result['prompt_eval_count']}",
        "输出tokens": f"   💬 输出tokens: {result['eval_count']}",
    }
    
    print("📈 性能指标:")
    for key, value in metrics.items():
        print(f"  {key}: {value}")
    


analyze_response(response)

---

6. 实际应用场景

📝 文本生成服务

import requests
import json

class OllamaTextGenerator:
    def __init__(self, base_url="http://localhost:11434"):
        self.base_url = base_url
        self.generate_url = f"{base_url}/api/generate"
    
    def generate_article(self, topic, length="medium"):
        """生成文章"""
        length_map = {
            "short": 200,
            "medium": 500,
            "long": 1000
        }
        
        payload = {
            "model": "gemma3:1b",
            "prompt": f"请写一篇关于'{topic}'的文章",
            "options": {
                "num_predict": length_map.get(length, 500),
                "temperature": 0.7
            }
        }
        
        response = requests.post(self.generate_url, json=payload)
        all_responses, complete_text = parse_streaming_json_response(response)
        return complete_text
    
    def summarize_text(self, text):
        """文本摘要"""
        payload = {
            "model": "gemma3:1b",
            "prompt": f"请总结以下文本的要点：\n\n{text}",
            "options": {"temperature": 0.3}
        }
        
        response = requests.post(self.generate_url, json=payload)
        all_responses, complete_text = parse_streaming_json_response(response)
        return complete_text

def parse_streaming_json_response(response):
   """解析流式JSON响应"""
   content = response.content.decode('utf-8')
   lines = content.strip().split('\n')
   
   all_responses = []
   complete_text = ""
   
   for line in lines:
       if line.strip():
           try:
               json_obj = json.loads(line)
               all_responses.append(json_obj)
               
               if 'response' in json_obj:
                   complete_text += json_obj['response']
               
           except json.JSONDecodeError:
               pass
   
   return all_responses, complete_text


# 使用示例
generator = OllamaTextGenerator()
article = generator.generate_article("人工智能的发展趋势", "medium")
summary = generator.summarize_text(article)
print("\n📰 生成的文章:")
print(article)
print("\n📑 文章摘要:")
print(summary)
print("\n🎉 代码执行成功！")

🤖 智能问答系统

import requests
import json
class OllamaQASystem:
    def __init__(self):
        self.context_history = []
        self.max_history = 5
    
    def ask_question(self, question):
        """带上下文的问答"""
        # 构建上下文
        context = "\n".join(self.context_history[-self.max_history:])
        
        prompt = f"""
基于以下对话历史回答问题：
{context}

当前问题：{question}

请给出准确、有用的回答：
"""
        
        payload = {
            "model": "gemma3:1b",
            "prompt": prompt,
            "options": {
                "temperature": 0.6,
                "num_ctx": 4096
            }
        }
        
        response = requests.post(
            "http://localhost:11434/api/generate", 
            json=payload
        )
        
        _,answer = parse_streaming_json_response(response)
        
        # 更新对话历史
        self.context_history.append(f"Q: {question}")
        self.context_history.append(f"A: {answer}")
        
        return answer

def parse_streaming_json_response(response):
   """解析流式JSON响应"""
   content = response.content.decode('utf-8')
   lines = content.strip().split('\n')
   
   all_responses = []
   complete_text = ""
   
   for line in lines:
       if line.strip():
           try:
               json_obj = json.loads(line)
               all_responses.append(json_obj)
               
               if 'response' in json_obj:
                   complete_text += json_obj['response']
               
           except json.JSONDecodeError:
               pass
   
   return all_responses, complete_text

# 使用示例
qa_system = OllamaQASystem()
answer1 = qa_system.ask_question("什么是机器学习？")
answer2 = qa_system.ask_question("它有哪些应用？")  # 会基于前一个问答的上下文
print("回答1:", answer1)
print("回答2:", answer2)
print(qa_system.context_history)

---

7. 总结与思考

🎯 核心收获

通过学习Ollama REST API，我深刻体会到了本地化大模型部署的优势：

1. 🚀 高效便捷：简洁的REST API设计，让模型调用变得极其简单
2. 🔒 数据安全：本地化部署确保数据隐私和安全性
3. 💰 成本可控：无需支付云端API费用，硬件成本可控
4. ⚡ 响应迅速：本地调用避免了网络延迟问题

🔮 应用前景

• 企业级应用：构建私有化AI服务
• 个人项目：开发AI驱动的应用程序
• 学习研究：深入理解大模型的工作原理
• 原型开发：快速验证AI产品想法

💡 最佳实践建议

1. 合理配置参数：根据任务特点调整温度、上下文等参数
2. 资源管理：注意模型的加载和卸载，避免内存溢出
3. 错误处理：实现完善的异常处理和重试机制
4. 性能监控：定期检查API调用的性能指标
5. 版本管理：保持Ollama和模型版本的更新

---

📚 参考资料

• Ollama官方文档
• 动手学Ollama项目
• REST API最佳实践指南

---

🙏 致谢

感谢DataWhale团队的辛勤付出，为开源社区贡献了这么优秀的教程资源！

---

如果这篇文章对你有帮助，请点赞👍、收藏⭐、关注🔔，你的支持是我继续创作的动力！

有问题欢迎在评论区讨论，我会及时回复！ 💬

---

🏷️ 标签: #Ollama #大模型 #本地部署 #CPU部署 #AI #机器学习 #开源项目 #DataWhale