- Features
- Installation
- Prerequisites
- Usage
- API Documentation
- Spring Boot Integration
- Development
- Contributing
- License
A Java client for the Ollama API, providing a simple and efficient way to interact with Ollama's language models.
- Text Generation
- Support for streaming responses
- Customizable generation parameters
- System prompt and template support
- Chat Functionality
- Multi-turn conversation support
- Role-based message handling
- Streaming chat responses
- Text Embedding
- Vector embeddings for text
- Support for multiple models
- Model Management
- List available models
- Delete models
- Model information retrieval
- Advanced Features
- Full support for Ollama API parameters
- Comprehensive error handling
- Detailed logging with SLF4J
- Spring Boot integration
- Configurable HTTP client
- Customizable timeouts
Download the latest release from the releases page and add it to your project's dependencies.
- Java 8 or higher
- Ollama server running locally or accessible via network
macOS
curl -fsSL https://ollama.com/install.sh | shLinux
curl -fsSL https://ollama.com/install.sh | shWindows
- Download the installer from Ollama's official website
- Run the installer and follow the setup wizard
After installation, start the Ollama service:
ollama serveIn a new terminal, you can pull the recommended model:
ollama pull qwen2.5:7bimportcom.matrixhero.ollama.client.OllamaClient; importcom.matrixhero.ollama.client.model.*; // Create clientOllamaClientclient = newOllamaClient(); // Generate textGenerateRequestrequest = newGenerateRequest(); request. setModel("qwen2.5:7b"); // Recommended modelrequest. setPrompt("Tell me a story"); GenerateResponseresponse = client.generate(request); System.out. println(response.getResponse()); // ChatChatRequestchatRequest = newChatRequest(); chatRequest. setModel("qwen2.5:7b"); // Recommended modelchatRequest. setMessages(Arrays.asList( newMessage(Message.Role.USER, "Hello, how are you?") )); ChatResponsechatResponse = client.chat(chatRequest); System.out. println(chatResponse.getMessage(). getContent()); // Stream generationrequest. setStream(true); client. generateStream(request) . forEach(r ->System.out. print(r.getResponse()));We recommend using the Qwen model (qwen2.5:7b) for best performance and quality. Qwen is a powerful language model developed by Alibaba Cloud, offering excellent performance in both English and Chinese tasks.
For more information about Qwen, please visit:
- GitHub: QwenLM/Qwen
- Model Card: Qwen/Qwen2.5-7B
GenerateRequestrequest = newGenerateRequest(); request.setModel("qwen2.5:7b"); request.setPrompt("Your prompt here"); request.setSystem("Optional system prompt"); request.setTemplate("Optional template"); request.setContext(newlong[]{...}); // Optional contextrequest.setStream(true); // Enable streamingrequest.setOptions(newOptions()); // Optional generation optionsGenerateResponseresponse = client.generate(request);ChatRequestrequest = newChatRequest(); request.setModel("qwen2.5:7b"); request.setMessages(Arrays.asList( newMessage(Message.Role.USER, "User message"), newMessage(Message.Role.ASSISTANT, "Assistant message") )); request.setStream(true); // Enable streamingrequest.setOptions(newOptions()); // Optional generation optionsChatResponseresponse = client.chat(request);EmbedRequestrequest = newEmbedRequest(); request.setModel("qwen2.5:7b"); request.setInput("Text to embed"); EmbedResponseresponse = client.embed(request); float[] embedding = response.getEmbedding();ListResponseresponse = client.list(); List<Model> models = response.getModels();DeleteRequestrequest = newDeleteRequest(); request.setName("model-name"); client.delete(request);The client includes comprehensive error handling:
try{GenerateResponseresponse = client.generate(request)} catch (IOExceptione){// Handle network errorslog.error("Error generating text", e)} catch (Exceptione){// Handle other errorslog.error("Unexpected error", e)}The client uses SLF4J for logging. Configure your logging framework to see detailed logs:
<dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.2.11</version> </dependency>If you're using Spring Boot, you can easily integrate the Ollama client:
@ConfigurationpublicclassOllamaConfig{@BeanpublicOllamaClientollamaClient(){returnnewOllamaClient()} }git clone https://github.com/yourusername/ollama-java.git cd ollama-java ./gradlew build./gradlew testContributions are welcome! Please feel free to submit a Pull Request. Before submitting, please:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
A: The client connects to http://localhost:11434 by default. You can configure a different URL using the OllamaClient constructor.
A: The client includes built-in retry mechanisms for rate limiting. You can configure retry behavior through the client options.
A: Yes, the client supports all Ollama models. We recommend Qwen for best performance, but you can use any model available in your Ollama installation.
Check out our examples directory for more detailed usage examples:
You can configure various timeout settings for the client using the builder pattern:
// Create a client with custom timeoutsOllamaClientclient = newOllamaClient() .withConnectTimeout(60) .withReadTimeout(120) .withWriteTimeout(60); // Or set timeouts individuallyOllamaClientclient = newOllamaClient() .withConnectTimeout(60) .withReadTimeout(120) .withWriteTimeout(60);Default timeout values:
- Connection timeout: 10 seconds
- Read timeout: 30 seconds
- Write timeout: 10 seconds
When a timeout occurs, the client will throw an OllamaTimeoutException with a descriptive message indicating which operation timed out. You can catch this exception to handle timeout scenarios:
try{ChatResponseresponse = client.chat(request)} catch (OllamaTimeoutExceptione){// Handle timeoutSystem.err.println("Request timed out: " + e.getMessage())} catch (IOExceptione){// Handle other IO errorsSystem.err.println("IO error: " + e.getMessage())}The client supports integration with external APIs through agents. Here's how to use agents:
// Create a weather agent (API key will be loaded from environment or system properties)WeatherAgentweatherAgent = newWeatherAgent(); // Add the agent to the clientOllamaClientclient = newOllamaClient() .withAgent(weatherAgent); // Now you can chat with the model, and it will automatically use the weather agent when appropriateChatRequestrequest = newChatRequest(); request.setModel("qwen2.5:7b"); request.setMessages(Arrays.asList( newMessage(Message.Role.USER, "What's the weather in New York?") )); ChatResponseresponse = client.chat(request); System.out.println(response.getMessage().getContent());For agents that require API keys (like WeatherAgent), you can configure them in two ways:
- Environment Variable:
export OPENWEATHERMAP_API_KEY=your_api_key_here- System Property:
java -Dopenweathermap.api.key=your_api_key_here -jar your-application.jarThe agent will first check for the environment variable, then fall back to the system property. If neither is found, it will throw an IllegalStateException with a helpful message.
Ollama API 的 Java 客户端，提供简单高效的方式与 Ollama 的语言模型进行交互。
- 文本生成
- 支持流式响应
- 可定制生成参数
- 系统提示词和模板支持
- 聊天功能
- 多轮对话支持
- 基于角色的消息处理
- 流式聊天响应
- 文本嵌入
- 文本向量嵌入
- 支持多种模型
- 模型管理
- 列出可用模型
- 删除模型
- 模型信息检索
- 高级功能
- 完整支持 Ollama API 参数
- 全面的错误处理
- 详细的日志记录
- Spring Boot 集成
- 可配置的 HTTP 客户端
- 可自定义的超时设置
从 releases 页面 下载最新版本并添加到你的项目依赖中。
- Java 8 或更高版本
- 本地运行或通过网络可访问的 Ollama 服务器
macOS
curl -fsSL https://ollama.com/install.sh | shLinux
curl -fsSL https://ollama.com/install.sh | shWindows
- 从 Ollama 官网 下载安装程序
- 运行安装程序并按照安装向导操作
安装完成后，启动 Ollama 服务：
ollama serve在新的终端中，你可以拉取推荐的模型：
ollama pull qwen2.5:7bimportcom.matrixhero.ollama.client.OllamaClient; importcom.matrixhero.ollama.client.model.*; // 创建客户端OllamaClientclient = newOllamaClient(); // 生成文本GenerateRequestrequest = newGenerateRequest(); request. setModel("qwen2.5:7b"); // 推荐模型request. setPrompt("讲个故事"); GenerateResponseresponse = client.generate(request); System.out. println(response.getResponse()); // 聊天ChatRequestchatRequest = newChatRequest(); chatRequest. setModel("qwen2.5:7b"); // 推荐模型chatRequest. setMessages(Arrays.asList( newMessage(Message.Role.USER, "你好，最近怎么样？") )); ChatResponsechatResponse = client.chat(chatRequest); System.out. println(chatResponse.getMessage(). getContent()); // 流式生成request. setStream(true); client. generateStream(request) . forEach(r ->System.out. print(r.getResponse()));我们推荐使用 Qwen 模型（qwen2.5:7b）以获得最佳性能和质量。Qwen 是由阿里云开发的强大语言模型，在英文和中文任务中都表现出色。
关于 Qwen 的更多信息，请访问：
- GitHub: QwenLM/Qwen
- 模型卡片: Qwen/Qwen2.5-7B
GenerateRequestrequest = newGenerateRequest(); request.setModel("qwen2.5:7b"); request.setPrompt("你的提示词"); request.setSystem("可选的系统提示词"); request.setTemplate("可选的模板"); request.setContext(newlong[]{...}); // 可选的上下文request.setStream(true); // 启用流式输出request.setOptions(newOptions()); // 可选的生成选项GenerateResponseresponse = client.generate(request);ChatRequestrequest = newChatRequest(); request.setModel("qwen2.5:7b"); request.setMessages(Arrays.asList( newMessage(Message.Role.USER, "用户消息"), newMessage(Message.Role.ASSISTANT, "助手消息") )); request.setStream(true); // 启用流式输出request.setOptions(newOptions()); // 可选的生成选项ChatResponseresponse = client.chat(request);EmbedRequestrequest = newEmbedRequest(); request.setModel("qwen2.5:7b"); request.setInput("要嵌入的文本"); EmbedResponseresponse = client.embed(request); float[] embedding = response.getEmbedding();ListResponseresponse = client.list(); List<Model> models = response.getModels();DeleteRequestrequest = newDeleteRequest(); request.setName("模型名称"); client.delete(request);客户端包含全面的错误处理：
try{GenerateResponseresponse = client.generate(request)} catch (IOExceptione){// 处理网络错误log.error("生成文本时出错", e)} catch (Exceptione){// 处理其他错误log.error("意外错误", e)}客户端使用 SLF4J 进行日志记录。配置你的日志框架以查看详细日志：
<dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.2.11</version> </dependency>如果你使用 Spring Boot，可以轻松集成 Ollama 客户端：
@ConfigurationpublicclassOllamaConfig{@BeanpublicOllamaClientollamaClient(){returnnewOllamaClient()} }git clone https://github.com/yourusername/ollama-java.git cd ollama-java ./gradlew build./gradlew test贡献是受欢迎的！请随时提交 Pull Request。
本项目采用 MIT 许可证 - 详见 LICENSE 文件。
A: The client connects to http://localhost:11434 by default. You can configure a different URL using the OllamaClient constructor.
A: The client includes built-in retry mechanisms for rate limiting. You can configure retry behavior through the client options.
A: Yes, the client supports all Ollama models. We recommend Qwen for best performance, but you can use any model available in your Ollama installation.
查看我们的 examples 目录 获取更详细的使用示例：
你可以使用构建器模式配置客户端的各种超时设置：
// Create a client with custom timeoutsOllamaClientclient = newOllamaClient() .withConnectTimeout(60) .withReadTimeout(120) .withWriteTimeout(60); // Or set timeouts individuallyOllamaClientclient = newOllamaClient() .withConnectTimeout(60) .withReadTimeout(120) .withWriteTimeout(60);Default timeout values:
- Connection timeout: 10 seconds
- Read timeout: 30 seconds
- Write timeout: 10 seconds
When a timeout occurs, the client will throw an OllamaTimeoutException with a descriptive message indicating which operation timed out. You can catch this exception to handle timeout scenarios:
try{ChatResponseresponse = client.chat(request)} catch (OllamaTimeoutExceptione){// Handle timeoutSystem.err.println("Request timed out: " + e.getMessage())} catch (IOExceptione){// Handle other IO errorsSystem.err.println("IO error: " + e.getMessage())}客户端支持通过 agents 集成外部 API。以下是使用 agents 的方法：
// 创建天气 agent（API key 将从环境变量或系统属性中加载）WeatherAgentweatherAgent = newWeatherAgent(); // 将 agent 添加到客户端OllamaClientclient = newOllamaClient() .withAgent(weatherAgent); // 现在你可以与模型聊天，当输入合适时它会自动使用天气 agentChatRequestrequest = newChatRequest(); request.setModel("qwen2.5:7b"); request.setMessages(Arrays.asList( newMessage(Message.Role.USER, "北京天气如何？") )); ChatResponseresponse = client.chat(request); System.out.println(response.getMessage().getContent());对于需要 API key 的 agents（如 WeatherAgent），你可以通过两种方式配置：
- 环境变量：
export OPENWEATHERMAP_API_KEY=your_api_key_here- 系统属性：
java -Dopenweathermap.api.key=your_api_key_here -jar your-application.jaragent 会首先检查环境变量，如果没有找到则使用系统属性。如果两者都没有找到，它会抛出一个带有帮助信息的 IllegalStateException。