【四】Ollama API 开发指南

1. API 基础配置

1.1 服务配置

# 设置服务地址和端口
export OLLAMA_HOST=0.0.0.0:11434
export OLLAMA_ORIGINS=*

# 启动服务
ollama serve

1.2 API 基础信息

• 基础 URL: http://localhost:11434
• 默认端口: 11434
• 支持协议: HTTP/HTTPS
• 响应格式: JSON

2. API 接口详解

2.1 模型管理接口

2.1.1 获取模型列表

# 请求示例
curl http://localhost:11434/api/tags

# 响应示例
{
  "models": [
    {
      "name": "llama2:7b",
      "modified_at": "2024-03-20T10:00:00Z",
      "size": 13000000000,
      "digest": "sha256:1234567890"
    }
  ]
}

2.1.2 拉取模型

# 请求示例
curl http://localhost:11434/api/pull -d '{
  "name": "llama2:7b"
}'

# 响应示例
{
  "status": "success",
  "digest": "sha256:1234567890"
}

2.2 模型运行接口

2.2.1 生成文本

# 请求示例
curl http://localhost:11434/api/generate -d '{
  "model": "llama2:7b",
  "prompt": "你好，请介绍一下自己",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 1000
  }
}'

# 响应示例
{
  "response": "你好！我是一个基于 Llama2 7B 模型训练的 AI 助手...",
  "done": true
}

2.2.2 流式生成

# 请求示例
curl http://localhost:11434/api/generate -d '{
  "model": "llama2:7b",
  "prompt": "你好，请介绍一下自己",
  "stream": true,
  "options": {
    "temperature": 0.7
  }
}'

# 响应示例（流式）
data: {"response": "你好", "done": false}
data: {"response": "！我是一个", "done": false}
data: {"response": "基于 Llama2", "done": false}
data: {"response": " 7B 模型", "done": false}
data: {"response": "训练的 AI 助手...", "done": true}

3. 编程语言集成

3.1 Python 集成

import requests
import json

class OllamaClient:
    def __init__(self, base_url="http://localhost:11434"):
        self.base_url = base_url

    def generate(self, model, prompt, **options):
        url = f"{self.base_url}/api/generate"
        data = {
            "model": model,
            "prompt": prompt,
            "stream": False,
            "options": options
        }
        response = requests.post(url, json=data)
        return response.json()

# 使用示例
client = OllamaClient()
response = client.generate(
    model="llama2:7b",
    prompt="你好，请介绍一下自己",
    temperature=0.7,
    max_tokens=1000
)
print(response["response"])

3.2 JavaScript 集成

class OllamaClient {
    constructor(baseUrl = 'http://localhost:11434') {
        this.baseUrl = baseUrl;
    }

    async generate(model, prompt, options = {}) {
        const response = await fetch(`${this.baseUrl}/api/generate`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                model,
                prompt,
                stream: false,
                options
            })
        });
        return await response.json();
    }
}

// 使用示例
const client = new OllamaClient();
client.generate('llama2:7b', '你好，请介绍一下自己', {
    temperature: 0.7,
    max_tokens: 1000
}).then(response => {
    console.log(response.response);
});

4. 高级功能

4.1 上下文管理

class OllamaClient:
    def __init__(self, base_url="http://localhost:11434"):
        self.base_url = base_url
        self.context = []

    def generate_with_context(self, model, prompt, **options):
        # 添加上下文
        full_prompt = "\n".join(self.context + [prompt])
        
        # 生成响应
        response = self.generate(model, full_prompt, **options)
        
        # 更新上下文
        self.context.append(prompt)
        self.context.append(response["response"])
        
        # 限制上下文长度
        if len(self.context) > 10:
            self.context = self.context[-10:]
            
        return response

4.2 错误处理

class OllamaClient:
    def generate(self, model, prompt, **options):
        try:
            response = requests.post(
                f"{self.base_url}/api/generate",
                json={
                    "model": model,
                    "prompt": prompt,
                    "stream": False,
                    "options": options
                },
                timeout=30
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"请求失败: {e}")
            return None
        except json.JSONDecodeError as e:
            print(f"JSON 解析失败: {e}")
            return None

5. 最佳实践

5.1 性能优化

1. 使用连接池

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

class OllamaClient:
    def __init__(self, base_url="http://localhost:11434"):
        self.base_url = base_url
        self.session = requests.Session()
        
        # 配置重试策略
        retry_strategy = Retry(
            total=3,
            backoff_factor=1,
            status_forcelist=[500, 502, 503, 504]
        )
        adapter = HTTPAdapter(max_retries=retry_strategy)
        self.session.mount("http://", adapter)
        self.session.mount("https://", adapter)

2. 批量处理

class OllamaClient:
    async def batch_generate(self, model, prompts, **options):
        tasks = []
        for prompt in prompts:
            task = self.generate(model, prompt, **options)
            tasks.append(task)
        return await asyncio.gather(*tasks)

5.2 安全建议

1. 使用 HTTPS

class OllamaClient:
    def __init__(self, base_url="https://your-domain.com:11434"):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.verify = True  # 验证 SSL 证书

2. 认证机制

class OllamaClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}"
        })

6. 常见问题解决

6.1 连接问题

1. 超时处理

class OllamaClient:
    def generate(self, model, prompt, **options):
        try:
            response = self.session.post(
                f"{self.base_url}/api/generate",
                json={
                    "model": model,
                    "prompt": prompt,
                    "stream": False,
                    "options": options
                },
                timeout=(5, 30)  # 连接超时 5 秒，读取超时 30 秒
            )
            return response.json()
        except requests.exceptions.Timeout:
            print("请求超时")
            return None

2. 重试机制

from tenacity import retry, stop_after_attempt, wait_exponential

class OllamaClient:
    @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
    def generate(self, model, prompt, **options):
        response = self.session.post(
            f"{self.base_url}/api/generate",
            json={
                "model": model,
                "prompt": prompt,
                "stream": False,
                "options": options
            }
        )
        response.raise_for_status()
        return response.json()

7. 实际应用案例

7.1 聊天机器人

class ChatBot:
    def __init__(self, model="llama2:7b"):
        self.client = OllamaClient()
        self.model = model
        self.context = []

    def chat(self, message):
        # 添加上下文
        full_prompt = "\n".join(self.context + [f"用户: {message}"])
        
        # 生成响应
        response = self.client.generate(
            self.model,
            full_prompt,
            temperature=0.7,
            max_tokens=1000
        )
        
        # 更新上下文
        self.context.append(f"用户: {message}")
        self.context.append(f"助手: {response['response']}")
        
        return response["response"]

7.2 代码生成器

class CodeGenerator:
    def __init__(self, model="llama2:7b"):
        self.client = OllamaClient()
        self.model = model

    def generate_code(self, description, language="python"):
        prompt = f"""
        请用{language}语言实现以下功能：
        {description}
        
        要求：
        1. 代码要简洁高效
        2. 添加必要的注释
        3. 包含示例用法
        """
        
        response = self.client.generate(
            self.model,
            prompt,
            temperature=0.3,  # 降低随机性，使代码更稳定
            max_tokens=2000
        )
        
        return response["response"]

8. 总结与建议

1. API 开发注意事项

   • 合理设置超时时间
   • 实现错误重试机制
   • 注意上下文管理
   • 做好性能优化

2. 安全建议

   • 使用 HTTPS 协议
   • 实现认证机制
   • 保护 API 密钥
   • 限制访问频率

3. 性能优化建议

   • 使用连接池
   • 实现批量处理
   • 优化上下文管理
   • 监控资源使用