Spring AI + Ollama 离线私有化部署实战

2.2 模型拉取与量化选择

Ollama 的好处是拉模型比较直接，很多时候不用自己折腾量化文件。真正要纠结的，是选哪一档量化更合适。

# 拉取 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

# 查看本地模型列表
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 资源参数调整

把下面这些参数放到 /etc/ollama/config.json，能明显影响模型占用和响应方式：

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

实际上，num_gpu、low_vram 这两个参数最容易和机器条件打架。没 GPU 就把 num_gpu 设成 0；显存紧张时，low_vram 比硬扛要靠谱得多。

三、Spring AI 对接 Ollama

3.1 依赖引入

<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 配置

Spring AI 已经能直接接 Ollama，但默认配置通常只够演示。实际业务里，像上下文长度、温度、流式响应这些参数，还是得自己收一下。

/**
 * 自定义 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 核心接口

/**
 * 离线 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 接口验证

# 同步生成接口
curl -X POST http://localhost:8080/api/ai/generate \ 
-H "Content-Type: application/json" \ 
-d '{"prompt":"用 Java 写一个 Spring AI 调用 Ollama 的示例代码"}'

# 流式生成接口
curl -X POST http://localhost:8080/api/ai/stream \ 
-H "Content-Type: application/json" \ 
-d '{"prompt":"详细介绍 Spring AI 的核心功能"}'

四、模型优化：量化和资源控制

4.1 量化级别对比

在 16GB 内存服务器上，不同量化级别的 Llama3 8B 表现大致如下：

结论很直接：如果机器条件不是特别宽松，Q4_K_M 往往是最省心的选择。它不是最快，但综合下来最稳。想再往上提效果，可以看 Q5_K_M；如果内存太紧，Phi-3 Mini 这种小模型更实际。

4.2 常用优化手段

1. CPU 绑定：num_thread 尽量和 CPU 核数对齐，别让线程切来切去把性能磨没了。
2. 显存限制：low_vram 适合 GPU 不够用或者干脆没 GPU 的机器。
3. 上下文窗口：num_ctx 不要盲目拉大，够用就行。
4. 批量处理：batch_size 适当调大，吞吐会好一些，但也别把内存顶爆。

4.3 压测和调优

用 JMeter 跑 10 并发时，生成接口的表现如下：

如果压测里碰到 OOM，先看 num_ctx，很多时候不是模型本身不行，而是上下文开太大；如果是超时，就优先看 batch_size 和 CPU 线程数。

五、离线 RAG 知识库

5.1 流程图

5.2 本地部署配置

5.2.1 Chroma DB 本地配置

/**
 * 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 = "请基于以下上下文回答问题，若上下文没有相关信息，直接回答暂无相关信息：\n上下文：%s\n问题：%s".formatted(context, question);
        
        // 4. 调用大模型生成回答
        Prompt aiPrompt = new Prompt(new UserMessage(prompt));
        AiResponse response = ollamaChatClient.generate(aiPrompt);
        return response.getGeneration().getText();
    }
}

5.3 无外网环境适配

1. 模型离线包导入：先在有网环境把模型拉下来，再拷到离线服务器导入。
2. 文档离线导入：本地文档通过 importDocument 接口写入知识库。
3. 向量本地存储：./chroma-data 里保存全部向量数据，不依赖云端服务。

六、生产环境落地

6.1 高可用配置

1. 多实例部署：Docker Compose 起多个 Ollama 实例，再用 Nginx 做负载均衡。
2. 模型热切换：通过接口参数切换 Llama3、Qwen 等模型。
3. 容错处理：给大模型调用加重试和熔断，至少别让一次超时拖垮整条链路。

6.2 监控与告警

Prometheus + Grafana 适合拿来盯这些指标：

• Ollama 调用 QPS、响应时间、错误率；
• CPU、内存、显存占用；
• RAG 检索召回率、向量生成速度。

6.3 日志排查

@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. 模型微调：针对企业内部业务做定制化适配。
2. 多模型调度：Llama3、Qwen、Phi3 按场景切换。
3. 知识库增量更新：只更新新增文档，不必每次全量重建。
4. 分布式部署：Kubernetes 承接扩缩容。
5. 国产化适配：接入文心一言、通义千问等国产模型，满足信创环境。

结语

这套方案的核心不复杂：把模型、推理、向量库和文档都收回本地，尽量让链路闭环。Ollama 负责把模型跑起来，Spring AI 负责把接口接进业务，Chroma DB 负责把知识库撑住。真正要花时间的，不是把 demo 跑通，而是把量化、上下文、显存和离线导入这些细节调到能长期用的状态。