Ollama-rs

一个简单易用的库，用于与 Ollama API 进行交互。

该库是根据 Ollama API 文档编写的。

目录

• 安装
• 初始化
• 使用
  • 生成补全
  • 生成补全（流式）
  • 生成补全（带选项）
  • 聊天模式
  • 列出本地模型
  • 显示模型信息
  • 创建模型
  • 创建模型（流式）
  • 复制模型
  • 删除模型
  • 生成嵌入
  • 生成嵌入（批量）
  • 调用函数
  • 创建自定义工具
  • 生成补全（带思考）

安装

将 ollama-rs 添加到你的 Cargo.toml 文件中

[dependencies]
ollama-rs = "0.3.4"

如果你确实想要最新版本，可以通过在 Cargo.toml 文件中添加以下内容来使用 master 分支：

[dependencies]
ollama-rs = { git = "https://github.com/pepperoni21/ollama-rs.git", branch = "master" }

请注意，master 分支可能不稳定，并且可能包含破坏性更改。

初始化

初始化 Ollama

use ollama_rs::Ollama;

// 默认会连接到 localhost:11434
let ollama = Ollama::default();

// 自定义值：
let ollama = Ollama::new("http://localhost".to_string(), 11434);

使用

欢迎查看 聊天机器人示例，它展示了如何使用该库在不到 50 行代码内创建一个简单的聊天机器人。你也可以查看一些 其他示例。

这些示例为了简单起见使用了较差的错误处理，但在你的代码中应该妥善处理错误。

生成补全

use ollama_rs::generation::completion::GenerationRequest;

let model = "llama2:latest".to_string();
let prompt = "为什么天空是蓝色的？".to_string();

let res = ollama.generate(GenerationRequest::new(model, prompt)).await;

if let Ok(res) = res {
    println!("{}", res.response);
}

输出： 天空呈现蓝色是因为一种称为瑞利散射的现象……

生成补全（流式）

需要启用 stream 功能。

use ollama_rs::generation::completion::GenerationRequest;
use tokio::io::{self, AsyncWriteExt};
use tokio_stream::StreamExt;

let model = "llama2:latest".to_string();
let prompt = "为什么天空是蓝色的？".to_string();

let mut stream = ollama.generate_stream(GenerationRequest::new(model, prompt)).await.unwrap();

let mut stdout = io::stdout();
while let Some(res) = stream.next().await {
    let responses = res.unwrap();
    for resp in responses {
        stdout.write_all(resp.response.as_bytes()).await.unwrap();
        stdout.flush().await.unwrap();
    }
}

与上述相同，但以流式方式输出。

生成补全（带选项）

use ollama_rs::generation::completion::GenerationRequest;
use ollama_rs::models::ModelOptions;

let model = "llama2:latest".to_string();
let prompt = "为什么天空是蓝色的？".to_string();

let options = ModelOptions::default()
    .temperature(0.2)
    .repeat_penalty(1.5)
    .top_k(25)
    .top_p(0.25);

let res = ollama.generate(GenerationRequest::new(model, prompt).options(options)).await;

if let Ok(res) = res {
    println!("{}", res.response);
}

输出： 1. 太阳发出白光：太阳主要由……

聊天模式

每次发送和接收的消息都会被存储在库的历史记录中。

带有历史记录的示例：

use ollama_rs::generation::chat::{request::ChatMessageRequest, ChatMessage};
use ollama_rs::history::ChatHistory;

let model = "llama2:latest".to_string();
let prompt = "为什么天空是蓝色的？".to_string();
// `Vec<ChatMessage>` 实现了 `ChatHistory`，
// 但你也可以在自定义类型上自行实现
let mut history = vec![];

let res = ollama
    .send_chat_messages_with_history(
        &mut history, // <- 消息将保存在这里
        ChatMessageRequest::new(
            model,
            vec![ChatMessage::user(prompt)], // <- 应该只提供一条消息
        ),
    )
    .await;

if let Ok(res) = res {
    println!("{}", res.message.content);
}

请查看带有历史记录的聊天示例，包括 默认模式 和 流式模式。

列出本地模型

let res = ollama.list_local_models().await.unwrap();

返回一个 LocalModel 结构体的向量。

显示模型信息

let res = ollama.show_model_info("llama2:latest".to_string()).await.unwrap();

返回一个 ModelInfo 结构体。

创建模型

use ollama_rs::models::create::CreateModelRequest;

let res = ollama.create_model(CreateModelRequest::new("my_model".into())
    .system("你是一个聊天机器人。".into())
    .from_model("llama2:latest".into())).await.unwrap();

返回一个 CreateModelStatus 结构体，表示模型创建的最终状态。

创建模型（流式）

需要启用 stream 功能。

use ollama_rs::models::create::CreateModelRequest;
use tokio_stream::StreamExt;

let res = ollama.create_model_stream(CreateModelRequest::new("my_model".into())
    .system("你是一个聊天机器人。".into())
    .from_model("llama2:latest".into())).await.unwrap();

while let Some(res) = res.next().await {
    let res = res.unwrap();
    // 处理状态
}

返回一个 CreateModelStatusStream，它会流式传输模型创建过程中的每一个状态更新。

复制模型

let _ = ollama.copy_model("mario".into(), "mario_copy".into()).await.unwrap();

删除模型

let _ = ollama.delete_model("mario_copy".into()).await.unwrap();

生成嵌入

use ollama_rs::generation::embeddings::request::GenerateEmbeddingsRequest;

let request = GenerateEmbeddingsRequest::new("llama2:latest".to_string(), "为什么天空是蓝色的？".to_string());
let res = ollama.generate_embeddings(request).await.unwrap();

生成嵌入（批量）

use ollama_rs::generation::embeddings::request::GenerateEmbeddingsRequest;

let request = GenerateEmbeddingsRequest::new("llama2:latest".to_string(), vec!["为什么天空是蓝色的？", "为什么天空是红色的？"].into());
let res = ollama.generate_embeddings(request).await.unwrap();

返回一个包含嵌入（浮点数向量）的 GenerateEmbeddingsResponse 结构体。

调用函数

use ollama_rs::coordinator::Coordinator;
use ollama_rs::generation::chat::{ChatMessage, ChatMessageRequest};
use ollama_rs::generation::tools::implementations::{DDGSearcher, Scraper, Calculator};
use ollama_rs::models::ModelOptions;

let mut history = vec![];

let mut coordinator = Coordinator::new(ollama, "qwen2.5:32b".to_string(), history)
    .options(ModelOptions::default().num_ctx(16384))
    .add_tool(DDGSearcher::new())
    .add_tool(Scraper {})
    .add_tool(Calculator {});

let resp = coordinator
    .chat(vec![ChatMessage::user("当前油价是多少？")])
    .await.unwrap();

println!("{}", resp.message.content);

使用提供的工具（例如网络搜索）查找答案，将该答案反馈给大模型，并返回包含问题答案的 ChatMessageResponse。

创建自定义工具

function 宏简化了自定义工具的创建过程。下面是一个用于获取指定城市当前天气的工具示例：

/// 获取指定城市的天气。
///
/// * city - 需要查询天气的城市。
#[ollama_rs::function]
async fn get_weather(city: String) -> Result<String, Box<dyn std::error::Error + Sync + Send>> {
    let url = format!("https://wttr.in/{city}?format=%C+%t");
    let response = reqwest::get(&url).await?.text().await?;
    Ok(response)
}

要创建自定义工具，只需定义一个返回 Result<String, Box<dyn std::error::Error + Sync + Send>> 的函数，并使用 function 宏对其进行标注。该函数将自动转换为可与 Coordinator 一起使用的工具，与其他工具无异。

请确保函数上方的文档注释清晰地描述了工具的作用及其参数。这些信息将提供给大模型，帮助其理解如何使用该工具。

如需更详细的示例，请参阅 函数调用示例。

完成生成（带思考）

let model = "qwen3:latest".to_string();
let prompt = "为什么天空是蓝色的？".to_string();

let res = ollama.generate(GenerationRequest::new(model, prompt).think(true)).await;

if let Ok(res) = res {
    println!("{}", res.response);
}

Ollama-rs 快速上手指南

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows。
• Rust 工具链: 已安装 Rust 和 Cargo (推荐通过 rustup 安装)。
• Ollama 服务: 本地已安装并运行 Ollama 服务。
  • 默认监听地址：http://localhost:11434
  • 确保已拉取至少一个模型（例如：ollama pull llama2:latest）。
• 异步运行时: 由于库基于 tokio，你的项目需要配置异步运行时（通常在 main 函数添加 #[tokio::main]）。

安装步骤

在你的 Rust 项目根目录下的 Cargo.toml 文件中，添加 ollama-rs 依赖：

[dependencies]
ollama-rs = "0.3.4"
tokio = { version = "1", features = ["full"] }

提示：如果你需要使用流式输出（Streaming）功能，需启用 stream 特性：

ollama-rs = { version = "0.3.4", features = ["stream"] }

若需使用最新的开发版功能（可能包含不稳定变更），可使用 Git 源：

[dependencies]
ollama-rs = { git = "https://github.com/pepperoni21/ollama-rs.git", branch = "master" }

基本使用

以下是最简单的文本生成示例，展示如何初始化客户端并调用模型回答问题。

1. 初始化与简单生成

use ollama_rs::Ollama;
use ollama_rs::generation::completion::GenerationRequest;

#[tokio::main]
async fn main() {
    // 初始化 Ollama 客户端 (默认连接 localhost:11434)
    let ollama = Ollama::default();

    // 设置模型和提示词
    let model = "llama2:latest".to_string();
    let prompt = "Why is the sky blue?".to_string();

    // 发送生成请求
    let res = ollama.generate(GenerationRequest::new(model, prompt)).await;

    // 处理结果
    if let Ok(res) = res {
        println!("{}", res.response);
    } else {
        eprintln!("Error: {:?}", res.err());
    }
}

2. 带参数的生成（可选）

你可以通过 ModelOptions 调整温度、重复惩罚等参数：

use ollama_rs::models::ModelOptions;

let options = ModelOptions::default()
    .temperature(0.2)
    .repeat_penalty(1.5);

let res = ollama.generate(
    GenerationRequest::new("llama2:latest".to_string(), "Hello".to_string())
    .options(options)
).await;

3. 对话模式（保留历史）

ollama-rs 支持自动管理对话历史：

use ollama_rs::generation::chat::{ChatMessage, ChatMessageRequest};
use ollama_rs::history::ChatHistory;

let mut history = vec![]; // 用于存储对话历史

let res = ollama
    .send_chat_messages_with_history(
        &mut history,
        ChatMessageRequest::new(
            "llama2:latest".to_string(),
            vec![ChatMessage::user("Who are you?")],
        ),
    )
    .await;

if let Ok(res) = res {
    println!("{}", res.message.content);
}

注意：以上示例为了简洁省略了部分错误处理细节，在生产环境中请务必完善 Result 的处理逻辑。更多高级用法（如流式输出、工具调用、自定义 Function Call）请参考官方 examples 目录。