概要

本文将用最简洁的 Java 示例（Python版本请查看：本地AI Agent Hello World(Python版)），带你逐步完成本地大模型 Agent 的“Hello World”：

1、介绍核心工具组件：Ollama、LangChain、langchain4j；

2、进行环境安装；

3、通过一段完整的 Java 代码示例，实现本地启动、调用大模型，并构建你的第一个本地 AI Agent 智能体。

在动手之前，不妨先了解一下本地构建 AI Agent 的四大优势：

数据本地留存：全程无需外发，杜绝传输泄露风险；

合规与隐私：满足 GDPR、HIPAA 等严格法规对数据本地化的要求；

独立可控：摆脱在线服务的策略调整与网络波动影响；

机密保护：关键研发与商业数据绝不外泄，最大程度保全知识产权。

接下来，我们将直接进入核心组件的介绍与实操讲解，让你在最短时间内完成本地 AI Agent 的“Hello World”的搭建。

Ollama

客户端 (Client) 与服务端 (Server) 分离

Ollama 采用经典的前后端分离架构：客户端（CLI 或 SDK）负责向用户暴露命令与接口，服务端（用 Go 实现的 ollama-http-server）则提供 REST API，二者通过本机 HTTP 通信完成指令下发与结果回传 。

Modelfile：模型与配置的一体化

1、Modelfile 将模型权重、tokenizer、系统提示（system prompt）及运行参数打包在同一个目录或文件中，类似于 Docker 镜像的概念，一次 ollama pull <model> 即可获取全部所需资源。

2、通过 ollama show <model> 可以快速查看 Modelfile 的元数据信息，如模型大小、license、支持的硬件加速等 。

推理引擎与硬件加速

1、Ollama 内部集成了高效的推理后端（如 llama.cpp），支持 CPU 多线程与 GPU CUDA 加速，能够在无 GPU 的设备（例如 Raspberry Pi）上也执行基本推理 。

2、用户可在 Modelfile 中指定 device: gpu 或通过环境变量控制并发线程数，以达到性能与资源利用的最佳平衡 。

LangChain

核心接口与模块划分

LangChain 将 LLM 应用拆分为若干可组合的接口与模块，包括：

1、Models：封装各种 LLM 提供者（本地 Ollama、OpenAI、Anthropic 等）的统一调用接口。

2、Prompts：定义 Prompt 模板与变量注入规则，简化大规模 Prompt 管理。

3、Chains：可串联的执行单元，将多个调用（如检索→生成→解析）组成流水线。

4、Tools：第三方 API、脚本或自定义函数的抽象化，可由 Agent 动态调度。

5、Agents：具备“感知—决策—执行”循环的智能体，自动选择适当 Tools 处理复杂任务。

多样化存储与记忆（Memory & Indexes）

1、Memory：提供对话历史、检索结果等上下文的持久化方案，支持短期（会话级）和长期（文件级）记忆管理 。

2、Indexes/Vector Stores：结合向量检索框架（如 FAISS、Weaviate）实现 RAG（Retrieval-Augmented Generation），将外部文档作为 Prompt 源增强回答准确性 。

LangChain4j

LangChain4j 的目标是为 Java 开发者提供一个统一的 API，支持多种 LLM 提供商（如 OpenAI、Google Vertex AI）和嵌入式存储（如 Pinecone、Vespa），使开发者无需深入了解各自的专有 API，即可轻松切换和集成不同的模型和存储方案 。

核心功能与模块

模型输入输出（Model I/O）

1、Models：集成多种大语言模型，提供统一的调用接口。

2、Prompts：定义提示词模板，简化大规模 Prompt 管理。

3、Output Parsers：格式化模型输出，便于后续处理。

数据连接与索引（Data Connection & Indexes）

1、Vector Stores：支持非结构化数据的向量存储，便于语义搜索。

2、Document Loaders：加载不同类型的数据源。

3、Transformers：进行数据转换和预处理。

4、Retrievers：实现文档数据的高效检索。

记忆与对话管理（Memory）

提供对话历史的持久化方案，支持多轮对话的上下文管理，提升模型的交互性 。

工具与代理（Tools & Agents）

1、Tools：封装第三方 API、自定义函数等，扩展模型能力。

2、Agents：具备“感知—决策—执行”循环的智能体，自动选择适当的工具处理复杂任务。

环境安装

硬件与系统要求

1、操作系统：macOS、Linux（Ubuntu/Debian）或 Windows Subsystem for Linux（WSL）均可。

2、硬件：建议至少 8 GB 内存，若要较流畅地运行 7B 以上级别模型，需配备 NVIDIA/AMD GPU（安装对应驱动）或 Apple Silicon 芯片。

安装 Ollama

命令行安装

1、Linux / macOS：curl -fsSL
https://ollama.com/install.sh | sh

2、macOS：也可通过 brew install ollama 安装

3、Windows (PowerShell)：iwr
https://ollama.com/install.ps1 -useb | iex

官网下载安装

官网地址：
https://ollama.com/download

根据系统自行选择下载安装即可。

安装成功检验

在终端里面输入：ollama serve

在浏览器例如输入：http://127.0.0.1:11434，出现“Ollama is running”说明安装成功。

安装本地大模型

在 https://ollama.com/search 里面找到自己需要的大模型，我本地安装了 qwen3:1.7b 和 deepseek-r1:8b。使用命令 ollama pull qwen3:1.7b 安装；

安装完后，可以通过 ollama list 查看本地安装的大模型。

Java及依赖安装

下载对应代码示例：
https://github.com/joyang1/AI_Agent_Java_Demos

示例代码使用SpringBoot项目来开发，同时使用maven来做java包管理，你需要引入如下依赖：

<!-- springboot start -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- springboot end -->

<!-- langchain4j start -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>${langchain4j.version}</version>
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-ollama-spring-boot-starter</artifactId>
    <version>1.0.0-beta4</version>
</dependency>
<!-- langchain4j end -->

代码运行

CLI代码运行

package com.ai.agent.demos.customchat;

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.ollama.OllamaChatModel;

public class CustomChatAgentCLi {

    final ChatModel chatModel;

    private static final String MODEL_NAME = "deepseek-r1:8b";

    private static final String MODEL_TYPE = "deepseek";

    /**
     * 设置chatModel
     */
    public CustomChatAgentCLi() {
        this.chatModel = OllamaChatModel.builder().baseUrl("http://127.0.0.1:11434").modelName(MODEL_NAME).build();
    }

    /**
     * 基础聊天
     *
     * @param userInput 用户输入
     * @return 模型返回
     */
    public String chat(String userInput) {
        return this.chatModel.chat(userInput);
    }

    /**
     * 获取模型类型
     *
     * @return 模型类型
     */
    public String getModelType() {
        return MODEL_TYPE;
    }

    public static void main(String[] args) {
        System.out.println(new CustomChatAgentCLi().chat("你是谁？"));
    }
}

Idea CLI里面直接运行上述代码，模型响应如下：

结合IDEA插件Cool Request来访问http接口

我本地的AI Agent是假如它是篮球明星詹姆斯，模拟詹姆斯的语气跟我对话。你可以输入任意的主题跟他对话。

SpringBoot项目启动后，在对应Rest API使用Cool Request 访问API

下面你可以输入任意篮球话题与其对话，比如我输入： 帮我评价下科比、乔丹，同时你认为你们三谁更强？。

输出如下：