Spring AI 实战：基于 Ollama 构建离线私有化 AI 服务

2.1.2 启动与端口验证

# 启动 Ollama 服务（默认端口 11434）
ollama serve
# 验证端口监听
netstat -tulpn | grep 11434
# 输出：tcp 0 0 127.0.0.1:11434 0.0.0.0:* LISTEN 1234/ollama

2.2 模型拉取与量化级别选择

Ollama 支持一键拉取量化模型，无需手动处理量化压缩，核心量化级别及适用场景如下：

2.2.1 拉取量化模型（推荐 Q4_K_M）

# 拉取 Llama3 8B Q4_K_M（平衡精度与性能）
ollama pull llama3:8b-q4_K_M
# 拉取 Qwen 7B Q4_K_M（国产模型，适配中文场景）
ollama pull qwen:7b-q4_K_M
# 拉取 Phi-3 Mini Q2_K（极致轻量化，适合开发测试）
ollama pull phi3:mini-q2_K

2.2.2 验证模型部署

# 查看本地模型列表
ollama list
# 输出：
# NAME ID SIZE MODIFIED
# llama3:8b-q4_K_M 78e26419b446 4.7 GB 2 minutes ago
# 命令行交互验证
ollama run llama3:8b-q4_K_M "用 Java 写一个 Spring Boot Hello World"
# 输出完整的 Java 代码，验证模型正常运行

2.3 核心参数配置（资源优化）

修改 Ollama 配置文件（/etc/ollama/config.json），优化资源占用：

{
  "num_ctx": 4096,
  "num_gpu": 1,
  "num_thread": 8,
  "batch_size": 512,
  "low_vram": true
}

💡 实战提示：若服务器无 GPU，需将 num_gpu 设为 0，强制使用 CPU 推理；若显存不足（如 16GB 显存运行 8B 模型），开启 low_vram 可显著降低显存占用。

三、Spring AI 对接 Ollama：自定义 ModelClient 实现

3.1 核心依赖引入

在 pom.xml 中添加 Spring AI 与 Ollama 的依赖：

<dependencies>
  <!-- Spring AI 核心依赖 -->
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
    <version>0.8.1</version>
  </dependency>
  <!-- Spring Web -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <!-- LangChain4j（RAG 支持） -->
  <dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.27.0</version>
  </dependency>
</dependencies>

3.2 自定义 Ollama ModelClient 配置

Spring AI 原生支持 Ollama，但默认实现无法满足复杂的业务需求（如自定义上下文窗口、流式响应优化），因此需要自定义 ModelClient：

/**
 * 自定义 Ollama ModelClient，支持流式响应与参数优化
 */
@Configuration
public class OllamaConfig {
  @Value("${ollama.base-url:http://localhost:11434}")
  private String baseUrl;
  
  @Value("${ollama.model:llama3:8b-q4_K_M}")
  private String model;
  
  @Bean
  public OllamaChatClient ollamaChatClient() {
    OllamaApi ollamaApi = OllamaApi.builder()
      .baseUrl(baseUrl)
      .build();
    return new OllamaChatClient(ollamaApi)
      .withModel(model)
      .withTemperature(0.2) // 低温度保证输出稳定性
      .withTopP(0.9)
      .withNumCtx(4096) // 与 Ollama 配置保持一致
      .withStream(true); // 开启流式响应
  }
}

3.3 核心 API 实现（生成 + 流式响应）

/**
 * 离线 AI 核心接口
 */
@RestController
@RequestMapping("/api/ai")
public class AiController {
  @Autowired
  private OllamaChatClient ollamaChatClient;

  /**
   * 同步生成接口
   */
  @PostMapping("/generate")
  public Result<String> generate(@RequestBody AiRequest request) {
    Prompt prompt = new Prompt(new UserMessage(request.getPrompt()));
    AiResponse response = ollamaChatClient.generate(prompt);
    return Result.success(response.getGeneration().getText());
  }

  /**
   * 流式生成接口（适合大文本输出）
   */
  @PostMapping("/stream")
  public SseEmitter streamGenerate(@RequestBody AiRequest request) {
    SseEmitter emitter = new SseEmitter(60000L); // 超时时间 60 秒
    Prompt prompt = new Prompt(new UserMessage(request.getPrompt()));
    ollamaChatClient.stream(prompt).subscribe(
      chunk -> {
        try {
          emitter.send(chunk.getGeneration().getText());
        } catch (IOException e) {
          emitter.completeWithError(e);
        }
      },
      emitter::completeWithError,
      emitter::complete
    );
    return emitter;
  }
}

// 请求实体类
@Data
public class AiRequest {
  private String prompt; // 用户输入的提示词
  private String model; // 可选，指定模型（默认使用配置的模型）
}

3.4 接口验证

通过 Postman 调用接口，验证离线 AI 服务正常运行：

# 同步生成接口
curl -X POST http://localhost:8080/api/ai/generate \\n  -H "Content-Type: application/json" \\n  -d '{"prompt":"用 Java 写一个 Spring AI 调用 Ollama 的示例代码"}'
# 流式生成接口
curl -X POST http://localhost:8080/api/ai/stream \\n  -H "Content-Type: application/json" \\n  -d '{"prompt":"详细介绍 Spring AI 的核心功能"}'

四、模型优化：量化压缩与资源占用控制

4.1 量化级别实战对比

在 16GB 内存服务器上，不同量化级别 Llama3 8B 模型的资源占用对比：

💡 实战结论：Q4_K_M 是性价比最高的选择，在 16GB 内存服务器上可稳定运行，响应速度与精度达到平衡；若追求极致性能，可选择 Q5_K_M；若服务器内存不足 8GB，建议选择 Phi-3 Mini Q2_K。

4.2 资源占用优化技巧

1. CPU 绑定：在 Ollama 配置中设置 num_thread 与服务器核心数匹配（如 8 核服务器设为 8），避免线程上下文切换；
2. 显存限制：开启 low_vram 模式，强制模型使用 CPU 推理，适合无 GPU 或显存不足的场景；
3. 上下文窗口调整：根据业务需求调整 num_ctx（默认 4096），减少不必要的内存占用；
4. 批量处理优化：设置 batch_size 为 512 或 1024，提升并发请求的处理效率。

4.3 性能压测与调优

使用 JMeter 对生成接口进行压测，10 并发场景下的性能表现：

🚨 踩坑提示：若压测时出现 OOM 错误，需检查 num_ctx 是否过大，或降低量化级别；若出现响应超时，需调整 batch_size 或增加 CPU 线程数。

五、实战：离线 RAG 知识库部署（无外网环境适配）

5.1 RAG 核心流程

5.2 离线 RAG 核心配置

5.2.1 向量数据库（Chroma DB）本地部署

Chroma DB 支持纯 Java 本地部署，无需额外依赖，配置如下：

/**
 * Chroma DB 本地配置
 */
@Configuration
public class ChromaConfig {
  @Bean
  public Chroma chroma() {
    return Chroma.builder()
      .persistDirectory("./chroma-data") // 向量存储目录（本地文件）
      .build();
  }
}

5.2.2 文档导入与向量生成

/**
 * 知识库导入服务
 */
@Service
public class KnowledgeBaseService {
  @Autowired
  private Chroma chroma;
  
  @Autowired
  private OllamaEmbeddingClient embeddingClient;

  /**
   * 导入本地文档到知识库
   */
  public void importDocument(String filePath) throws IOException {
    // 1. 解析本地文档（支持 PDF/Word/Markdown）
    File file = new File(filePath);
    String content = FileUtils.readFileToString(file, StandardCharsets.UTF_8);
    // 2. 分割文档（按段落分割，避免上下文过长）
    List<String> chunks = RecursiveCharacterTextSplitter.builder()
      .chunkSize(1000)
      .chunkOverlap(200)
      .build()
      .split(content);
    // 3. 生成向量并存储
    List<Embedding> embeddings = embeddingClient.embed(chunks);
    for (int i = 0; i < chunks.size(); i++) {
      chroma.add(
        CollectionUtils.singletonList(UUID.randomUUID().toString()),
        CollectionUtils.singletonList(chunks.get(i)),
        embeddings.get(i).getEmbedding()
      );
    }
  }
}

5.2.3 RAG 问答接口实现

/**
 * RAG 问答核心服务
 */
@Service
public class RagQAService {
  @Autowired
  private Chroma chroma;
  
  @Autowired
  private OllamaEmbeddingClient embeddingClient;
  
  @Autowired
  private OllamaChatClient ollamaChatClient;

  /**
   * 基于知识库的问答
   */
  public String qa(String question) {
    // 1. 问题向量化
    Embedding questionEmbedding = embeddingClient.embed(question);
    // 2. 向量检索（返回 Top3 相关文档）
    List<Document> documents = chroma.query(
      questionEmbedding.getEmbedding(),
      3,
      null,
      null
    );
    // 3. 拼接上下文 Prompt
    String context = documents.stream()
      .map(Document::getContent)
      .collect(Collectors.joining("\n\n"));
    String prompt = String.format(
      "请基于以下上下文回答问题，若上下文没有相关信息，直接回答\"暂无相关信息\"：\n上下文：%s\n问题：%s",
      context,
      question
    );
    // 4. 调用大模型生成回答
    Prompt aiPrompt = new Prompt(new UserMessage(prompt));
    AiResponse response = ollamaChatClient.generate(aiPrompt);
    return response.getGeneration().getText();
  }
}

5.3 无外网环境适配

1. 模型离线包导入：若服务器无外网，可在有网环境下载模型离线包（ollama pull llama3:8b-q4_K_M --output llama3-8b-q4_K_M.tar），然后在离线服务器上导入（ollama create llama3:8b-q4_K_M -f llama3-8b-q4_K_M.tar）；
2. 文档离线导入：将本地文档上传到服务器，通过 importDocument 接口导入到知识库；
3. 向量存储本地化：Chroma DB 的向量存储在本地文件（./chroma-data），无需依赖云服务。

六、生产环境落地：高可用与监控

6.1 高可用配置

1. 多实例部署：通过 Docker Compose 部署多个 Ollama 实例，结合 Nginx 负载均衡，提升并发能力；
2. 模型热切换：支持动态切换模型（如 Llama3/Qwen），通过 API 参数指定模型；
3. 容错机制：为大模型调用添加重试、熔断（Resilience4j），避免服务雪崩。

6.2 监控与告警

整合 Prometheus+Grafana 实现服务监控，核心监控指标：

• Ollama 模型调用 QPS、响应时间、错误率；
• 服务器 CPU、内存、显存占用；
• RAG 知识库检索召回率、向量生成速度。

6.3 日志排查

为服务添加完整的日志体系，记录模型调用、RAG 检索、向量生成的详细日志，方便排查问题：

@Slf4j
@Service
public class AiCodeService {
  public String generateCode(String requirement) {
    log.info("生成代码请求：{}", requirement);
    try {
      Prompt prompt = new Prompt(new UserMessage(requirement));
      AiResponse response = ollamaChatClient.generate(prompt);
      log.info("生成代码响应：{}", response.getGeneration().getText());
      return response.getGeneration().getText();
    } catch (Exception e) {
      log.error("生成代码失败", e);
      throw new BusinessException("生成代码失败：" + e.getMessage());
    }
  }
}

七、实战踩坑与进阶规划

7.1 常见问题与解决方案

7.2 进阶规划

1. 模型微调：基于 Ollama 实现模型微调，适配企业专属业务场景；
2. 多模型融合：支持 Llama3/Qwen/Phi3 多模型调用，根据业务需求动态选择；
3. 知识库增量更新：支持文档增量导入与向量更新，无需全量重建；
4. 分布式部署：通过 Kubernetes 部署多实例，实现弹性扩缩容；
5. 国产化适配：适配文心一言、通义千问等国产大模型，满足信创需求。