Ollama API 完整接口文档

// 无需安装任何依赖，使用原生 fetch 即可
const OLLAMA_BASE = 'http://localhost:11434';

// 所有请求都是 POST (除少数 GET 接口)
const response = await fetch(`${OLLAMA_BASE}/api/generate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gemma3',
    prompt: '你好，世界！',
  }),
});
const data = await response.json();
console.log(data.response);

// 流式生成（逐行读取 NDJSON）
const response = await fetch('http://localhost:11434/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gemma3',
    prompt: '用简单的语言解释量子计算',
    stream: true,
    options: { temperature: 0.7 },
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

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

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop(); // 保留不完整行

  for (const line of lines) {
    if (!line.trim()) continue;
    const chunk = JSON.parse(line);
    process.stdout.write(chunk.response);
    if (chunk.done) console.log('\n[流结束]');
  }
}

import Ollama from 'ollama';
const ollama = new Ollama();

// 非流式 + 结构化 JSON 输出
const result = await ollama.generate({
  model: 'gemma3',
  prompt: '列出中国人口最多的5个城市，包含城市名和人口数',
  stream: false,
  format: {
    type: 'object',
    properties: {
      cities: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            name: { type: 'string' },
            population: { type: 'integer' },
          },
          required: ['name', 'population'],
        },
      },
    },
    required: ['cities'],
  },
});

const data = JSON.parse(result.response);
console.log('结构化结果:', JSON.stringify(data, null, 2));

// HTTP 非流式 + 结构化输出
const response = await fetch('http://localhost:11434/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gemma3',
    prompt: '列出中国人口最多的5个城市',
    stream: false,
    format: {
      type: 'object',
      properties: {
        cities: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              name: { type: 'string' },
              population: { type: 'integer' },
            },
            required: ['name', 'population'],
          },
        },
      },
      required: ['cities'],
    },
  }),
});

const data = await response.json();
console.log(JSON.parse(data.response));

import Ollama from 'ollama';
import { readFileSync } from 'fs';

const ollama = new Ollama();

// 读取图片并转为 Base64
const imageBuffer = readFileSync('./photo.jpg');
const imageBase64 = imageBuffer.toString('base64');

// 多模态图像识别
const result = await ollama.generate({
  model: 'gemma3',
  prompt: '这张图片里有什么？请详细描述。',
  images: [imageBase64],
  stream: false,
});

console.log(result.response);

// HTTP 图像识别
// 将本地图片转为 Base64
const fs = require('fs');
const imageBuffer = fs.readFileSync('./photo.jpg');
const imageBase64 = imageBuffer.toString('base64');

const response = await fetch('http://localhost:11434/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gemma3',
    prompt: '这张图片里有什么？请详细描述。',
    images: [imageBase64],
    stream: false,
  }),
});

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

// HTTP 多轮对话（非流式）
const response = await fetch('http://localhost:11434/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gemma3',
    stream: false,
    messages: [
      { role: 'system', content: '你是一个专业的编程助手。' },
      { role: 'user', content: '解释 JavaScript 的事件循环机制' },
    ],
  }),
});

const data = await response.json();
console.log(data.message.content);
console.log(`输出 ${data.eval_count} tokens，耗时 ${(data.eval_duration / 1e6).toFixed(0)}ms`);

import Ollama from 'ollama';
const ollama = new Ollama();

// 定义工具
const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: '获取指定城市的当前天气信息',
    parameters: {
      type: 'object',
      properties: {
        city: {
          type: 'string',
          description: '城市名称，如 "北京"',
        },
        unit: {
          type: 'string',
          enum: ['celsius', 'fahrenheit'],
          description: '温度单位',
        },
      },
      required: ['city'],
    },
  },
}];

// 第一轮：模型可能请求调用工具
const response1 = await ollama.chat({
  model: 'qwen3',
  messages: [{ role: 'user', content: '北京今天天气怎么样？' }],
  tools,
  stream: false,
});

if (response1.message.tool_calls?.length) {
  const toolCall = response1.message.tool_calls[0];
  console.log(`模型调用: ${toolCall.function.name}`, toolCall.function.arguments);

  // 模拟工具执行结果
  const weatherResult = '晴天，温度 22°C，微风';

  // 第二轮：将工具结果返回给模型
  const response2 = await ollama.chat({
    model: 'qwen3',
    messages: [
      { role: 'user', content: '北京今天天气怎么样？' },
      response1.message,
      {
        role: 'tool',
        content: weatherResult,
      },
    ],
    stream: false,
  });

  console.log('最终回复:', response2.message.content);
}

// HTTP 工具调用
const response = await fetch('http://localhost:11434/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'qwen3',
    messages: [
      { role: 'user', content: '巴黎今天天气如何？' },
    ],
    stream: false,
    tools: [{
      type: 'function',
      function: {
        name: 'get_current_weather',
        description: '获取指定地点的当前天气',
        parameters: {
          type: 'object',
          properties: {
            location: { type: 'string', description: '地点' },
            format: { type: 'string', enum: ['celsius', 'fahrenheit'] },
          },
          required: ['location', 'format'],
        },
      },
    }],
  }),
});

const data = await response.json();
console.log('工具调用:', data.message.tool_calls);

import Ollama from 'ollama';
const ollama = new Ollama();

// Thinking 模式 - 让模型先思考再回答
const response = await ollama.chat({
  model: 'gpt-oss',
  messages: [
    { role: 'user', content: '如果一个房间里有3个人，每两个人握手一次，一共握了几次手？' },
  ],
  think: 'low',  // 可选: true/false/"high"/"medium"/"low"
  stream: true,
});

let thinking = '';
let content = '';
for await (const chunk of response) {
  if (chunk.message.thinking) {
    thinking += chunk.message.thinking;
    process.stderr.write(chunk.message.thinking); // 思考过程
  }
  if (chunk.message.content) {
    content += chunk.message.content;
    process.stdout.write(chunk.message.content); // 最终答案
  }
}

// HTTP Thinking 模式（流式读取）
const response = await fetch('http://localhost:11434/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gpt-oss',
    messages: [
      { role: 'user', content: '如果一个房间里有3个人，每两个人握手一次，一共握了几次手？' },
    ],
    think: 'low',
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

console.log('=== 思考过程 ===');
while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();

  for (const line of lines) {
    if (!line.trim()) continue;
    const chunk = JSON.parse(line);
    if (chunk.message?.thinking) {
      process.stderr.write(chunk.message.thinking);
    }
    if (chunk.message?.content) {
      process.stdout.write(chunk.message.content);
    }
  }
}

// HTTP 批量嵌入
const response = await fetch('http://localhost:11434/api/embed', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'embeddinggemma',
    input: [
      '什么是机器学习？',
      '深度学习与传统机器学习的区别',
      '如何训练一个神经网络',
    ],
    dimensions: 128,
  }),
});

const data = await response.json();
console.log(`模型: ${data.model}`);
console.log(`向量数: ${data.embeddings.length}`);
console.log(`维度: ${data.embeddings[0].length}`);
console.log(`耗时: ${(data.total_duration / 1e6).toFixed(0)}ms`);

import Ollama from 'ollama';
const ollama = new Ollama();

// 实际用法: 语义搜索
function cosineSimilarity(a, b) {
  const dot = a.reduce((s, v, i) => s + v * b[i], 0);
  const magA = Math.sqrt(a.reduce((s, v) => s + v * v, 0));
  const magB = Math.sqrt(b.reduce((s, v) => s + v * v, 0));
  return dot / (magA * magB);
}

const docs = [
  'Python 是一种通用编程语言',
  '机器学习使用统计方法让计算机学习',
  'React 是一个前端 JavaScript 框架',
];

// 生成文档嵌入
const docEmbeddings = await ollama.embed({ model: 'embeddinggemma', input: docs });

// 生成查询嵌入
const query = '什么是 AI';
const queryEmbed = await ollama.embed({ model: 'embeddinggemma', input: query });

// 计算相似度并排序
const results = docEmbeddings.embeddings
  .map((emb, i) => ({
    text: docs[i],
    score: cosineSimilarity(queryEmbed.embeddings[0], emb),
  }))
  .sort((a, b) => b.score - a.score);

console.log('搜索结果:', results);

// HTTP 列出模型
const response = await fetch('http://localhost:11434/api/tags');
const { models } = await response.json();

for (const m of models) {
  console.log(`${m.name} - ${(m.size / 1e9).toFixed(2)} GB`);
}

// HTTP 查看模型详情
const response = await fetch('http://localhost:11434/api/show', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'gemma3', verbose: true }),
});

const info = await response.json();
console.log('能力:', info.capabilities);
console.log('模型信息:', info.model_info);

// HTTP 创建模型
const response = await fetch('http://localhost:11434/api/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'emoji-bot',
    from: 'gemma3',
    system: '你只会用表情符号回答问题。',
    stream: false,
  }),
});

const result = await response.json();
console.log(result.status); // "success"

import Ollama from 'ollama';
const ollama = new Ollama();

// 创建量化版本模型（减少显存占用）
const stream = await ollama.create({
  model: 'llama3:8b-q4',
  from: 'llama3:8b-instruct-fp16',
  quantize: 'q4_K_M',  // 量化到 Q4_K_M 级别
  stream: true,
});

for await (const chunk of stream) {
  if (chunk.total && chunk.completed) {
    const pct = ((chunk.completed / chunk.total) * 100).toFixed(1);
    console.log(`量化进度: ${pct}%`);
  }
}

await fetch('http://localhost:11434/api/copy', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source: 'gemma3',
    destination: 'gemma3-backup',
  }),
});
console.log('复制完成'); // 成功返回 200

// HTTP 删除模型 (注意是 DELETE 方法)
await fetch('http://localhost:11434/api/delete', {
  method: 'DELETE',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'gemma3-backup' }),
});
console.log('模型已删除');

// HTTP 下载模型并跟踪进度
const response = await fetch('http://localhost:11434/api/pull', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'gemma3' }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

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

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();

  for (const line of lines) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);
    if (event.total) {
      console.log(`${event.status}: ${((event.completed / event.total) * 100).toFixed(1)}%`);
    }
  }
}

// HTTP 推送模型
const response = await fetch('http://localhost:11434/api/push', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'my-username/my-model',
    stream: false,
  }),
});

const result = await response.json();
console.log(result.status); // "success"

// HTTP 列出运行中的模型
const response = await fetch('http://localhost:11434/api/ps');
const { models } = await response.json();

console.log(`运行中: ${models.length} 个模型`);
for (const m of models) {
  console.log(`  ${m.name} → VRAM: ${(m.size_vram / 1e9).toFixed(2)} GB`);
}

// HTTP 获取版本
const response = await fetch('http://localhost:11434/api/version');
const { version } = await response.json();
console.log(`Ollama 版本: ${version}`);