AI 模块 — Vostok 文档

初始化

通过 Vostok.AI.init() 初始化模块，可传入 VKAiConfig 覆盖全局默认配置。

// 使用默认配置初始化
Vostok.AI.init();

// 使用自定义配置初始化
Vostok.AI.init(new VKAiConfig()
    .connectTimeoutMs(3000)
    .readTimeoutMs(60_000)
    .maxRetries(2)
    .metricsEnabled(true)
    .auditEnabled(true)
    .securityCheckEnabled(true)
    .agentLoopEnabled(true)
    .maxAgentLoops(5)
    .tokenBudgetPerRequest(0)        // 0 = 不限制
    .ragCacheEnabled(true)
);

VKAiConfig 配置项

方法	类型	默认值	说明
`connectTimeoutMs(long)`	long	3000	HTTP 连接超时（毫秒）
`readTimeoutMs(long)`	long	30000	HTTP 读取超时（毫秒）
`maxRetries(int)`	int	1	最大重试次数
`retryBackoffMs(long)`	long	150	首次重试等待时间（毫秒）
`maxRetryBackoffMs(long)`	long	1500	最大重试等待时间（毫秒）
`retryOnStatuses(Integer...)`	Set<Integer>	429,500,502,503,504	触发重试的 HTTP 状态码
`retryOnNetworkError(boolean)`	boolean	true	网络异常时是否重试
`retryOnTimeout(boolean)`	boolean	true	超时时是否重试
`failOnNon2xx(boolean)`	boolean	true	非 2xx 响应时是否抛出异常
`metricsEnabled(boolean)`	boolean	true	是否启用指标采集
`logEnabled(boolean)`	boolean	false	是否启用请求日志
`toolCallingEnabled(boolean)`	boolean	true	是否允许 Tool Call
`securityCheckEnabled(boolean)`	boolean	true	是否启用安全扫描（XSS/注入检测）
`blockOnSecurityRisk(boolean)`	boolean	true	安全风险时是否阻断请求
`auditEnabled(boolean)`	boolean	true	是否启用审计记录
`maxToolCallsPerRequest(int)`	int	8	单次请求最大 Tool Call 次数
`maxAuditRecords(int)`	int	1000	内存中保留的最大审计记录数
`ragCacheEnabled(boolean)`	boolean	true	是否启用 RAG 缓存（Embedding/Rerank/答案）
`embeddingCacheTtlMs(long)`	long	21600000	Embedding 缓存 TTL（毫秒，默认 6 小时）
`rerankCacheTtlMs(long)`	long	1800000	Rerank 缓存 TTL（毫秒，默认 30 分钟）
`ragAnswerCacheTtlMs(long)`	long	600000	RAG 答案缓存 TTL（毫秒，默认 10 分钟）
`ragRerankTimeoutMs(long)`	long	1500	RAG 内部 Rerank 超时（毫秒）
`agentLoopEnabled(boolean)`	boolean	true	是否启用 Agentic 多轮 Tool 循环
`maxAgentLoops(int)`	int	5	Agentic 循环最大轮次
`tokenBudgetPerRequest(int)`	int	0	全局 Token 预算上限（0 = 不限制）

注册模型

所有 API 调用通过模型名称路由，需先注册。VKAiModelType 区分模型用途：CHAT、EMBEDDING、RERANK。当前 Provider 支持 OPENAI_COMPATIBLE（兼容 OpenAI 接口格式的所有服务）。

// 注册 Chat 模型（OpenAI / 任何兼容 OpenAI 接口的服务）
Vostok.AI.registerModel("gpt4o", new VKAiModelConfig()
    .type(VKAiModelType.CHAT)
    .baseUrl("https://api.openai.com/v1")
    .model("gpt-4o")
    .apiKey(System.getenv("OPENAI_KEY"))
);

// 注册 Claude（通过 OpenAI 兼容代理或原生兼容层）
Vostok.AI.registerModel("claude", new VKAiModelConfig()
    .type(VKAiModelType.CHAT)
    .baseUrl("https://api.anthropic.com/v1")
    .model("claude-opus-4-6")
    .apiKey(System.getenv("ANTHROPIC_KEY"))
);

// 注册 Embedding 模型
Vostok.AI.registerModel("embed", new VKAiModelConfig()
    .type(VKAiModelType.EMBEDDING)
    .baseUrl("https://api.openai.com/v1")
    .model("text-embedding-ada-002")
    .apiKey(System.getenv("OPENAI_KEY"))
);

// 注册 Rerank 模型
Vostok.AI.registerModel("rerank", new VKAiModelConfig()
    .type(VKAiModelType.RERANK)
    .baseUrl("https://api.cohere.ai/v1")
    .model("rerank-multilingual-v2.0")
    .apiKey(System.getenv("COHERE_KEY"))
);

// 模型级别覆盖超时与重试（覆盖全局 VKAiConfig）
Vostok.AI.registerModel("slow-model", new VKAiModelConfig()
    .type(VKAiModelType.CHAT)
    .baseUrl("https://api.example.com/v1")
    .model("my-llm")
    .apiKey("...")
    .connectTimeoutMs(5000)
    .readTimeoutMs(120_000)
    .maxRetries(3)
    .putHeader("X-Custom-Header", "value")
);

VKAiModelConfig 配置项

方法	说明
`type(VKAiModelType)`	模型类型：CHAT / EMBEDDING / RERANK
`provider(VKAiProvider)`	Provider 协议，默认 OPENAI_COMPATIBLE
`baseUrl(String)`	API 基础 URL（必填）
`model(String)`	模型标识符，如 "gpt-4o"
`apiKey(String)`	API 密钥
`path(String)`	覆盖默认接口路径（如 /v1/chat/completions）
`connectTimeoutMs(long)`	覆盖连接超时（<= 0 时使用全局配置）
`readTimeoutMs(long)`	覆盖读取超时（<= 0 时使用全局配置）
`maxRetries(int)`	覆盖最大重试次数
`failOnNon2xx(Boolean)`	覆盖非 2xx 时是否抛异常（null 时使用全局配置）
`putHeader(String, String)`	追加固定请求头
`defaultHeaders(Map)`	设置全部固定请求头

单轮对话

VKAiChatRequest 使用链式调用构造请求，无需静态 builder。

// 同步 Chat
VKAiChatResponse res = Vostok.AI.chat(new VKAiChatRequest()
    .model("gpt4o")
    .system("你是一位物理学教授")
    .message("user", "用一句话解释量子纠缠")
    .temperature(0.7)
    .maxTokens(256)
);
System.out.println(res.getText());        // 模型回复文本
System.out.println(res.getFinishReason()); // "stop" / "length" / "tool_calls" 等
System.out.println(res.getLatencyMs());   // 请求耗时（毫秒）

// token 用量
VKAiUsage usage = res.getUsage();
System.out.println(usage.getPromptTokens() + usage.getCompletionTokens());

// 异步
CompletableFuture<VKAiChatResponse> future = Vostok.AI.chatAsync(new VKAiChatRequest()
    .model("gpt4o")
    .message("user", "Hello!")
);
future.thenAccept(r -> System.out.println(r.getText()));

VKAiChatRequest 参数

方法	说明
`model(String)`	已注册模型名称
`system(String)`	System Prompt
`message(String role, String content)`	追加一条消息，role 为 "user" 或 "assistant"
`message(VKAiMessage)`	追加 VKAiMessage 对象
`temperature(Double)`	采样温度（null 时使用模型默认值）
`maxTokens(Integer)`	最大输出 Token 数
`stream(boolean)`	是否启用流式输出，默认 false
`allowTool(String)`	允许本次请求使用的工具名称（可多次调用）
`allowTools(String...)`	批量设置允许工具白名单
`historyTrimEnabled(boolean)`	是否启用历史裁剪，默认 true
`historyMaxMessages(Integer)`	历史裁剪：最多保留的消息数
`historyMaxChars(Integer)`	历史裁剪：最多保留的总字符数
`responseFormat(String)`	结构化输出模式："json_object" 或 "json_schema"
`responseJsonSchema(String)`	JSON Schema 字符串，与 responseFormat("json_schema") 配合使用
`tokenBudgetTokens(Integer)`	本次请求 Token 预算上限（0 = 不限，null = 使用全局配置）

VKAiChatResponse 返回值

方法	返回类型	说明
`getText()`	String	模型回复文本
`getFinishReason()`	String	结束原因："stop" / "length" / "tool_calls" 等
`getUsage()`	VKAiUsage	Token 用量（promptTokens / completionTokens / totalTokens）
`getLatencyMs()`	long	请求耗时（毫秒）
`getStatusCode()`	int	HTTP 响应状态码
`getProviderRequestId()`	String	Provider 返回的请求 ID
`getToolResults()`	List<VKAiToolCallResult>	本次请求触发的 Tool Call 执行结果列表
`isStreaming()`	boolean	是否为流式响应
`stream()`	VKAiChatDeltaStream	流式输出对象（仅 stream=true 时非 null）

流式输出

VKAiChatResponse res = Vostok.AI.chat(new VKAiChatRequest()
    .model("gpt4o")
    .message("user", "写一首关于春天的诗")
    .stream(true)
);

VKAiChatDeltaStream stream = res.stream();
try {
    while (stream.hasNext(5000)) {   // 等待下一个 delta，超时 5 秒
        VKAiChatDelta delta = stream.next();
        System.out.print(delta.getContent()); // 增量文本
        if (delta.isDone()) break;
    }
    // 流结束后获取完整用量
    VKAiUsage usage = stream.finalUsage();
    System.out.println("\n结束原因: " + stream.finishReason());
} finally {
    stream.close();
}

// 取消流
stream.cancel();

VKAiChatDeltaStream 接口

方法	说明
`hasNext(long timeoutMs)`	是否还有下一个 delta，阻塞等待至多 timeoutMs 毫秒
`next()`	获取下一个 VKAiChatDelta（content + isDone）
`isDone()`	流是否已结束
`finalUsage()`	流结束后的完整 Token 用量（isDone() 后调用）
`finishReason()`	结束原因（isDone() 后调用）
`providerRequestId()`	Provider 请求 ID
`toolCalls()`	流中累积的 Tool Call 列表（isDone() 后调用）
`cancel()`	主动取消流
`close()`	释放资源（实现 AutoCloseable）

JSON 结构化输出

使用 chatJson 可直接将模型输出反序列化为 Java 对象。

record Sentiment(String label, double score) {}

Sentiment result = Vostok.AI.chatJson(
    new VKAiChatRequest()
        .model("gpt4o")
        .system("返回 JSON: {\"label\": \"positive/negative\", \"score\": 0.0~1.0}")
        .message("user", "分析评论的情感：'这个产品太棒了！'")
        .responseFormat("json_object"),
    Sentiment.class
);
System.out.println(result.label() + " " + result.score());

// 异步版本
CompletableFuture<Sentiment> future = Vostok.AI.chatJsonAsync(
    new VKAiChatRequest()
        .model("gpt4o")
        .message("user", "...")
        .responseFormat("json_object"),
    Sentiment.class
);

多轮会话

会话自动维护对话历史，支持跨请求的上下文传递。

// 创建会话（指定模型名称）
VKAiSession session = Vostok.AI.createSession("gpt4o");
String sessionId = session.getSessionId();

// 基于会话的多轮对话（自动携带历史）
VKAiChatResponse reply1 = Vostok.AI.chatSession(sessionId, "Java 有哪些主要特性？");
VKAiChatResponse reply2 = Vostok.AI.chatSession(sessionId, "它与 Go 有什么区别？");
System.out.println(reply1.getText());
System.out.println(reply2.getText());

// 获取会话信息
VKAiSession s = Vostok.AI.session(sessionId);
System.out.println(s.getCurrentModel()); // 当前模型名

// 查看历史消息列表
List<VKAiSessionMessage> history = Vostok.AI.sessionMessages(sessionId);
for (VKAiSessionMessage msg : history) {
    System.out.println(msg.getRole() + ": " + msg.getContent());
}

// 切换会话使用的模型（保留历史）
VKAiSession updated = Vostok.AI.switchSessionModel(sessionId, "claude");

// 更新会话 metadata
Vostok.AI.updateSessionMetadata(sessionId, Map.of("userId", "u-123", "scene", "support"));

// 删除会话
Vostok.AI.deleteSession(sessionId);

VKAiSession 字段

方法	返回类型	说明
`getSessionId()`	String	唯一会话 ID
`getCurrentModel()`	String	当前使用的模型名称
`getCreatedAt()`	long	创建时间戳（毫秒）
`getUpdatedAt()`	long	最后更新时间戳（毫秒）
`getMetadata()`	Map<String, String>	用户自定义元数据

VKAiSessionMessage 字段

方法	返回类型	说明
`getSessionId()`	String	所属会话 ID
`getSeq()`	long	消息序号（递增）
`getRole()`	String	"user" 或 "assistant"
`getContent()`	String	消息内容
`getModel()`	String	生成该消息时使用的模型名称
`getTimestamp()`	long	消息时间戳（毫秒）

自定义会话存储

默认使用内存存储。实现 VKAiMemoryStore 接口可接入数据库等持久化后端。

// 切换到内置的数据库存储（依赖 Vostok.Data 模块）
Vostok.AI.setMemoryStore(new VKAiDataMemoryStore());

// 或实现自定义存储
Vostok.AI.setMemoryStore(new VKAiMemoryStore() {
    public VKAiSession saveSession(VKAiSession s) { /* ... */ }
    public VKAiSession findSession(String id) { /* ... */ }
    public void appendMessage(VKAiSessionMessage msg) { /* ... */ }
    public List<VKAiSessionMessage> listMessages(String id) { /* ... */ }
    public void deleteSession(String id) { /* ... */ }
});

生成 Embedding

List<VKAiEmbedding> embeddings = Vostok.AI.embed(
    new VKAiEmbeddingRequest()
        .model("embed")
        .input("Vostok 是一个 Java 框架")
        .input("支持多模型 AI 集成")   // 可批量
);
List<Double> vector = embeddings.get(0).getVector(); // 第一个输入的向量
int dim = vector.size();                               // 向量维度

向量存储与检索

框架内置内存向量存储（VKAiInMemoryVectorStore，支持 BM25 关键词索引 + 余弦相似度），也可接入外部向量数据库。

// 写入向量文档（id + 文本 + 向量 + 可选 metadata）
Vostok.AI.upsertVectorDocs(List.of(
    new VKAiVectorDoc("doc-1", "Vostok 支持 Redis 缓存", vector1, null),
    new VKAiVectorDoc("doc-2", "Vostok 支持 MySQL 数据库", vector2,
        Map.of("category", "data", "lang", "zh"))
));

// 向量相似度检索（余弦相似度，返回 topK 条）
List<VKAiVectorHit> hits = Vostok.AI.searchVector(queryVector, 5);
for (VKAiVectorHit hit : hits) {
    System.out.println(hit.getId() + " score=" + hit.getScore());
    System.out.println(hit.getText());
    System.out.println(hit.getMetadata());
}

// 关键词检索（BM25）
List<VKAiVectorHit> kw = Vostok.AI.searchKeywords("Redis 缓存", 5);

// 清空向量存储
Vostok.AI.clearVectorStore();

// 接入外部向量数据库（实现 VKAiVectorStore 接口）
Vostok.AI.setVectorStore(myPineconeStore);

RAG（检索增强生成）

RAG 流程：自动完成文档分片 → Embedding → 向量/关键词混合检索 → 可选 Rerank → Context 压缩 → Chat 生成答案。

// 1. 写入文档到 RAG 知识库（自动分片 + 生成 Embedding + 写入向量存储）
VKAiRagIngestResult result = Vostok.AI.ingestRagDocument(
    new VKAiRagIngestRequest()
        .model("embed")            // Embedding 模型名
        .documentId("vostok-readme")
        .version("v1")            // 文档版本，默认 "v1"
        .text(readmeText)
        .chunkSize(500)           // 每块字符数，默认 500
        .chunkOverlap(80)         // 相邻块重叠字符数，默认 80
        .deduplicate(true)        // 内容相同的块自动跳过，默认 true
        .metadata("category", "docs")
);
System.out.println("写入 " + result.getInsertedChunks() + " 块");
System.out.println("跳过 " + result.getSkippedDuplicateChunks() + " 重复块");

// 2. RAG 查询
VKAiRagResponse ragRes = Vostok.AI.rag(
    new VKAiRagRequest()
        .chatModel("gpt4o")
        .embeddingModel("embed")
        .rerankModel("rerank")      // 可选，不设则跳过 Rerank
        .query("Vostok 支持哪些缓存后端？")
        .topK(3)                    // 最终送入 Chat 的 chunks 数，默认 4
        .vectorTopK(8)              // 向量检索候选数，默认 8
        .keywordTopK(8)             // 关键词检索候选数，默认 8
        .vectorWeight(0.65)         // 向量检索权重，默认 0.65
        .keywordWeight(0.35)        // 关键词检索权重，默认 0.35
        .rerankEnabled(true)
        .queryRewriteEnabled(true)  // 查询改写增强召回，默认 true
        .contextCompressionEnabled(true)
        .contextMaxChars(1800)      // Context 最大字符数，默认 1800
        .systemPrompt("你是 Vostok 框架专家")
);

String answer = ragRes.getAnswer().getText(); // Chat 模型生成的答案
List<VKAiVectorHit> sources = ragRes.getHits(); // 检索命中的文档列表
System.out.println(answer);
sources.forEach(h -> System.out.println("[" + h.getId() + "] " + h.getScore()));

// Metadata 过滤（AND 语义，只检索符合条件的文档）
VKAiRagResponse filtered = Vostok.AI.rag(
    new VKAiRagRequest()
        .chatModel("gpt4o")
        .embeddingModel("embed")
        .query("缓存策略")
        .metadataFilter("category", "docs")  // 仅检索 category=docs 的文档
);

VKAiRagIngestResult 字段

方法	说明
`getDocumentId()`	文档 ID
`getVersion()`	文档版本
`getTotalChunks()`	总分块数
`getInsertedChunks()`	实际写入块数
`getSkippedDuplicateChunks()`	跳过的重复块数
`getChunkIds()`	所有写入块的 ID 列表

重排序（Rerank）

VKAiRerankResponse reranked = Vostok.AI.rerank(
    new VKAiRerankRequest()
        .model("rerank")
        .query("Java 框架")
        .documents(List.of("Vostok 是 Java 框架", "Spring Boot 是...", "..."))
        .topK(2)
);
for (VKAiRerankResult r : reranked.getResults()) {
    System.out.println("原始索引: " + r.getIndex() + " 分数: " + r.getScore());
    System.out.println(r.getDocument());
}
System.out.println("耗时: " + reranked.getLatencyMs() + "ms");

Tool Call（函数调用）

实现 VKAiTool 接口注册工具。当 Chat 请求包含该工具的白名单时，框架自动执行工具并将结果回传给模型（Agentic 循环）。

// 实现 VKAiTool 接口
Vostok.AI.registerTool(new VKAiTool() {
    public String name() { return "get_weather"; }
    public String description() { return "获取指定城市的实时天气"; }
    public String inputJsonSchema() {
        return """
            {"type":"object","properties":{"city":{"type":"string","description":"城市名称"}},"required":["city"]}
            """;
    }
    public String outputJsonSchema() {
        return """
            {"type":"object","properties":{"temp":{"type":"number"},"desc":{"type":"string"}}}
            """;
    }
    public VKAiToolResult invoke(String inputJson) {
        // inputJson 为 LLM 传入的参数 JSON
        String result = fetchWeather(inputJson);
        return new VKAiToolResult(result); // 返回 JSON 字符串
    }
});

// 发起支持工具调用的对话（allowTool 设白名单）
VKAiChatResponse res = Vostok.AI.chat(new VKAiChatRequest()
    .model("gpt4o")
    .message("user", "北京今天天气怎么样？")
    .allowTool("get_weather")
);
System.out.println(res.getText());

// 查看触发的 Tool Call 结果
for (VKAiToolCallResult r : res.getToolResults()) {
    System.out.println(r.getToolName() + " success=" + r.isSuccess());
    System.out.println(r.getOutputJson());
}

// 手动执行工具
VKAiToolCallResult manual = Vostok.AI.callTool(
    new VKAiToolCall("call-1", "get_weather", "{\"city\":\"上海\"}")
);

// 工具管理
Set<String> names = Vostok.AI.toolNames(); // 已注册工具名称集合
Vostok.AI.clearTools();                     // 清除所有已注册工具

Prompt 模板

使用 ${变量名} 语法定义模板，注册后通过名称渲染。

// 注册模板
Vostok.AI.registerPrompt(new VKAiPromptTemplate(
    "sentiment",
    "你是一位情感分析专家，请用 JSON 返回分析结果",
    "分析以下评论的情感：${comment}"
));

// 渲染模板，获得 {"system": "...", "user": "..."}
Map<String, String> rendered = Vostok.AI.renderPrompt(
    "sentiment",
    Map.of("comment", "这个产品很好用！")
);

// 将渲染结果用于构建 Chat 请求
VKAiChatResponse res = Vostok.AI.chat(new VKAiChatRequest()
    .model("gpt4o")
    .system(rendered.get("system"))
    .message("user", rendered.get("user"))
    .responseFormat("json_object")
);

// 查看所有已注册模板名称
Set<String> names = Vostok.AI.promptNames();

审计与指标

// 获取最近 50 条审计记录
List<VKAiAuditRecord> records = Vostok.AI.audits(50);
for (VKAiAuditRecord r : records) {
    System.out.println(r.getTimestampMs() + " " + r.getType()
        + " " + r.getClientName() + " " + r.getDetail());
}
Vostok.AI.clearAudits(); // 清空审计记录

// 获取累计指标
VKAiMetrics m = Vostok.AI.metrics();
System.out.println("总调用: "      + m.totalCalls());
System.out.println("成功: "        + m.successCalls());
System.out.println("失败: "        + m.failedCalls());
System.out.println("重试: "        + m.retriedCalls());
System.out.println("超时: "        + m.timeoutCalls());
System.out.println("总耗时(ms): "  + m.totalCostMs());
System.out.println("总 Tokens: "  + m.totalTokens());
Vostok.AI.resetMetrics(); // 重置指标

RAG 健康检查

// 检查 Embedding 和 Rerank 模型连通性
Vostok.AI.healthCheckRag("embed", "rerank");

// 仅检查 Embedding 模型
Vostok.AI.healthCheckRag("embed", null, false);

生命周期

Vostok.AI.started();         // 是否已初始化
Vostok.AI.config();          // 获取当前 VKAiConfig
Vostok.AI.reinit(newConfig);  // 重新初始化（重置所有状态）
Vostok.AI.close();           // 关闭模块，释放资源

异常处理

所有异常均为 VKAiException（RuntimeException），包含 VKAiErrorCode 错误码。

try {
    VKAiChatResponse res = Vostok.AI.chat(req);
} catch (VKAiException e) {
    switch (e.getCode()) {
        case VKAiErrorCode.TIMEOUT           -> /* 超时重试 */
        case VKAiErrorCode.SECURITY_BLOCKED  -> /* 安全拦截 */
        case VKAiErrorCode.TOKEN_BUDGET_EXCEEDED -> /* 超出 Token 预算 */
        case VKAiErrorCode.HTTP_STATUS       -> /* HTTP 错误，e.getHttpStatus() 获取状态码 */
        default                              -> /* 其他错误 */
    }
}

错误码列表

错误码	说明
`INVALID_ARGUMENT`	参数非法（空值、格式错误等）
`CONFIG_ERROR`	配置错误（模型未注册、向量存储未设置等）
`STATE_ERROR`	状态错误（模块未初始化、会话不存在等）
`NETWORK_ERROR`	网络连接失败
`TIMEOUT`	请求超时
`HTTP_STATUS`	HTTP 非 2xx 响应
`SERIALIZATION_ERROR`	请求序列化失败
`JSON_PARSE_ERROR`	响应 JSON 解析失败
`TOOL_NOT_FOUND`	工具名称未注册
`TOOL_DENIED`	工具不在请求的白名单内
`TOOL_EXECUTION_ERROR`	工具执行抛出异常
`SECURITY_BLOCKED`	安全扫描拦截（XSS / 命令注入 / 路径遍历）
`TOKEN_BUDGET_EXCEEDED`	实际消耗 Token 超过预算上限

API 速查

方法	说明
`init()`	使用默认配置初始化模块
`init(VKAiConfig)`	使用自定义配置初始化模块
`reinit(VKAiConfig)`	重新初始化（重置所有状态）
`started()`	返回模块是否已初始化
`config()`	获取当前 VKAiConfig
`close()`	关闭模块，释放资源
`registerModel(name, VKAiModelConfig)`	注册命名 AI 模型
`chat(VKAiChatRequest)`	同步单轮对话，返回 VKAiChatResponse
`chatAsync(VKAiChatRequest)`	异步单轮对话，返回 CompletableFuture<VKAiChatResponse>
`chatJson(VKAiChatRequest, Class<T>)`	同步对话并反序列化为指定类型
`chatJsonAsync(VKAiChatRequest, Class<T>)`	异步对话并反序列化，返回 CompletableFuture<T>
`setMemoryStore(VKAiMemoryStore)`	设置自定义会话持久化存储
`createSession(model)`	创建多轮对话 Session，返回 VKAiSession
`session(sessionId)`	获取指定会话信息
`chatSession(sessionId, text)`	基于 Session 的对话，返回 VKAiChatResponse
`sessionMessages(sessionId)`	获取会话历史消息列表
`switchSessionModel(sessionId, model)`	切换会话使用的模型，返回更新后的 VKAiSession
`updateSessionMetadata(sessionId, Map)`	更新会话 metadata，返回更新后的 VKAiSession
`deleteSession(sessionId)`	删除会话及全部历史消息
`embed(VKAiEmbeddingRequest)`	生成文本 Embedding 向量，返回 List<VKAiEmbedding>
`rerank(VKAiRerankRequest)`	文档重排序，返回 VKAiRerankResponse
`setVectorStore(VKAiVectorStore)`	设置向量数据库后端
`upsertVectorDocs(List<VKAiVectorDoc>)`	写入/更新向量文档
`searchVector(List<Double>, int topK)`	向量相似度检索，返回 List<VKAiVectorHit>
`searchKeywords(String, int topK)`	BM25 关键词检索，返回 List<VKAiVectorHit>
`clearVectorStore()`	清空向量存储中的所有文档
`ingestRagDocument(VKAiRagIngestRequest)`	向 RAG 知识库写入并分片文档，返回 VKAiRagIngestResult
`rag(VKAiRagRequest)`	RAG 检索增强生成，返回 VKAiRagResponse
`healthCheckRag(embeddingModel, rerankModel)`	检查 Embedding 和 Rerank 模型连通性
`healthCheckRag(embeddingModel, rerankModel, includeRerank)`	健康检查，includeRerank=false 时仅检查 Embedding
`registerTool(VKAiTool)`	注册 Tool Call 工具
`clearTools()`	清除所有已注册工具
`toolNames()`	返回所有已注册工具名称集合
`callTool(VKAiToolCall)`	手动执行已注册的工具，返回 VKAiToolCallResult
`registerPrompt(VKAiPromptTemplate)`	注册 Prompt 模板
`renderPrompt(name, Map)`	渲染 Prompt 模板，返回 {"system": "...", "user": "..."}
`promptNames()`	返回所有已注册模板名称集合
`audits(int limit)`	获取最近 N 条审计记录
`clearAudits()`	清空审计记录
`metrics()`	获取累计指标（VKAiMetrics record）
`resetMetrics()`	重置所有指标计数器

AI 集成模块

初始化