第十三章：治理三件套：可观测性 + 安全 + 性能成本

13.1 可观测性：你得先能回答“发生了什么”

建议你的系统至少能回答这些问题：

• 哪个模型/哪个供应商在失败？
• 失败类型是 401/429/5xx 还是应用侧解析错误？
• P95 延迟是多少？峰值并发是多少？
• Token 用量与成本大概是多少？

最小落地：统一 Facade

把所有模型调用都收敛到一个 Facade（或拦截器）里，集中做：

• requestId
• 计时与失败计数
• 脱敏日志（不要打印 Key/手机号等）
• 错误分层（把供应商错误映射成业务可理解的错误）

13.2 安全：工具调用与 RAG 的“边界”必须由你控制

最危险的两类风险：

• Prompt 注入：诱导模型忽略规则、越权调用工具
• 数据泄露：把敏感数据塞进上下文或日志

最小安全基线

• 工具白名单：只注册你允许的工具
• 参数校验：空值、范围、格式、长度必须校验
• 最小权限：工具执行前做 RBAC/租户隔离
• 输出过滤：对外响应与日志都做脱敏
• 审计：记录 requestId、工具名、参数摘要、结果摘要

13.3 性能与成本：先稳，再省

推荐优先级：

1. 并发控制与超时（先止血）
2. 缓存（重复问题不重复花钱）
3. 上下文控制（减少 token）
4. 模型路由（按任务选模型）

13.3.1 并发闸门（最小实现）

package com.example.langchain4j.governance;

import java.time.Duration;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import org.springframework.stereotype.Component;

@Component
public class AiConcurrencyGuard {

    private final Semaphore semaphore = new Semaphore(8);

    public <T> T execute(Duration timeout, GuardedCall<T> call) throws Exception {
        boolean acquired = semaphore.tryAcquire(timeout.toMillis(), TimeUnit.MILLISECONDS);
        if (!acquired) {
            throw new IllegalStateException("系统繁忙，请稍后重试");
        }
        try {
            return call.invoke();
        } finally {
            semaphore.release();
        }
    }

    @FunctionalInterface
    public interface GuardedCall<T> {
        T invoke() throws Exception;
    }
}

13.3.2 缓存 key：用指纹，不要用原文

package com.example.langchain4j.governance;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Objects;

public final class PromptFingerprint {

    private PromptFingerprint() {
    }

    public static String sha256(String system, String user, String context) {
        String raw = Objects.toString(system, "") + "\n" + Objects.toString(user, "") + "\n" + Objects.toString(context, "");
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            return HexFormat.of().formatHex(digest.digest(raw.getBytes(StandardCharsets.UTF_8)));
        } catch (Exception ex) {
            throw new IllegalStateException("hash 失败", ex);
        }
    }
}

13.4 本章小结

这一章把“能跑”升级成“可上线”：

• 可观测性：requestId + 指标 + 错误分层
• 安全：白名单工具 + 校验 + 最小权限 + 审计
• 成本：并发闸门 + 缓存指纹 + 上下文控制 + 模型路由

下一章我们把本系列能力组合成一个可扩展的实战项目：知识库助手（RAG + Tools + SSE）。