Java 智能体实战：企业知识库 AI 系统“掌柜智库”完整开发教程

一、项目背景与技术选型

2026年初，笔者为某中型企业开发了知识库 AI 系统“掌柜智库”，目标是将散落在 Wiki、制度文档、技术手册中的企业知识统一管理，通过自然语言问答精准获取。技术栈选择上坚持“Java 原生优先”：Spring Boot 3.2 做基础框架，Spring AI 1.0.0-M2 做 LLM 抽象层，阿里云百炼（Qwen-Max）提供推理能力，pgvector 作为向量数据库，Elasticsearch 支撑关键词检索。

选型逻辑非常务实——企业技术基座全是 Java，引入 Python 栈意味着双倍运维成本。pgvector 相比 Milvus 省去一个独立组件，对 10 万级向量规模完全够用。

二、数据层：知识库基石

文档入库是第一个技术关口。PDF 解析需保留段落结构，笔者基于 PDFBox 实现，核心是在 startParagraph() 处插入双换行符，避免条款粘连。切片策略采用滑动窗口 + 语义边界检测：目标 500 字符/块，重叠 100 字符，切分时优先在句号、问号处断开，防止截断句子导致语义碎片。

CREATE TABLE knowledge_chunk (
    id BIGSERIAL PRIMARY KEY,
    doc_id VARCHAR(64) NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536),        -- pgvector 向量字段
    metadata JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_chunk_embedding ON knowledge_chunk 
    USING hnsw (embedding vector_cosine_ops);

向量化服务需做本地缓存：相同文本不重复调用嵌入模型，用 Caffeine 存储，命中率 30%+。

三、AI 能力层：RAG 核心链路

RAG 流程分为五步：意图识别 → 权限过滤 → 混合检索 → 上下文构建 → LLM 生成。

意图识别采用“规则优先 + LLM 兜底”，政策类关键词命中则跳过模型调用，降低 40% 成本。混合检索用加权融合：向量检索（权重 0.6）+ ES 关键词检索（权重 0.4），纯向量在专业术语密集场景下准确率仅 72%，融合后提升至 89%。

@Service
public class RagService {
    public RagResponse ask(RagRequest request) {
        // 1. 意图识别（规则+LLM）
        QueryIntent intent = intentClassifier.classify(question);
        // 2. 获取用户权限范围内的文档ID
        Set<String> accessibleDocs = permissionService.getAccessibleDocIds(userId);
        // 3. 混合检索（向量+关键词）
        List<KnowledgeChunk> chunks = hybridSearch(question, accessibleDocs, topK);
        // 4. 构建Prompt上下文
        String context = buildContext(chunks);
        // 5. LLM生成回答
        String answer = chatModel.call(buildPrompt(question, context, intent));
        return RagResponse.builder().answer(answer).citations(chunks).build();
    }
}

多轮对话用 Redis 存储最近 5 轮历史，过期时间 30 分钟。

四、知识导入流水线

文档导入是典型的长流程异步任务：上传 → 解析 → 切片 → 向量化 → 存入 pgvector → 写入 ES。必须异步化，笔者用 @Async 线程池处理，核心 2 线程，队列 50。批量向量化每批 20 条，10MB PDF 从 45 秒优化至 8 秒。

五、生产级保障

缓存策略分两级：Caffeine 本地缓存存重复问题的 LLM 结果，Redis 存跨实例共享，重复问题响应从 1.2s 降至 8ms，月度 LLM 费用控制在 ¥1200 左右。容错降级：LLM 超时时先查缓存，再走关键词模板匹配，最后转人工引导。

# pgvector + ES 双写保证混合检索能力
spring.ai.dashscope.model: qwen-max

监控用 Micrometer 记录问答耗时、检索延迟、成功率，告警阈值设为平均响应 >5s 或错误率 >3%。

六、总结

“掌柜智库”上线 3 个月，日均问答 1200+ 次，准确率 89.2%。笔者最深的体会是：企业 AI 系统 80% 的工作在 AI 之外——权限隔离、文档版本管理、审计日志这些“非 AI”功能占据了七成开发量，但正是它们让系统从 Demo 变成了可交付的产品。切片策略没有万能参数，需针对业务场景调优；混合检索是 RAG 落地的必修课，单靠向量检索撑不起企业级精度。Java 生态做 AI 完全可行，Spring AI 成熟度已足够支撑商用项目。