常用接入术语

接入架构

接入优势

• Chat****** 用同一套流式 API 支持同步 content、ChatResponse 元数据和 Reactor Flux。
• Spring *oot 属性可以显式设置兼容 *ase **L、密钥和模型，开发与生产环境容易隔离。
• entity() 可以把模型结果转换为 J**a record，减少手写 **ON 解析代码。
• ChatModel 抽象让***与具体模型配置解耦，便于测试、替换和故障切换。
• KingFlow 控制台集中管理模型、密钥和用量，便于隔离不同环境。

开始前的准备

• 准备 JDK 21、M**en 3.9 或更高版本，并安装常用 J**a IDE。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，确认余额和模型分组可用。
• 复制目标模型的完整模型 ID，并确认上下文窗口满足待处理文档长度。
• 准备少量脱敏测试文本，首次联调不要直接加载生产知识库。
• 确认运行环境可以访问 api.**nju**shen.com。

创建 Spring AI 测试项目

使用 Spring Initializr 创建 J**a 21 项目，选择 M**en 与 Spring We*Flux，再把以下 *OM 和依赖加入 pom.xml。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-*om</artifactId>
      <version>2.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.springframework.*oot</groupId>
    <artifactId>spring-*oot-starter-we*flux</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
  </dependency>
</dependencies>

验证 KingFlow 基础接口

先验证端点、密钥和模型；基础请求失败时不要继续排查 Spring AI 代码。

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role": "user", "content": "只回复 SPRING_AI_READY"}],
    "stream": false
  }'

配置环境变量

把配置保存为 src/**in/resources/application.yml，真实密钥由环境变量或 Secret 注入。

spring:
  ai:
    model:
      chat: openai
    openai:
      *ase-url: ${KINGFLOW_*ASE_**L:https://api.**nju**shen.com/v1}
      api-key: ${KINGFLOW_API_KEY}
      chat:
        model: ${KINGFLOW_MODEL}

.env
target/
.idea/
*.iml

编写文本生成示例

注入自动配置的 Chat******.*uilder，通过 call().content() 返回同步文本。

package com.example.kingflow;

import org.springframework.ai.chat.client.Chat******;
import org.springframework.we*.**nd.annotation.GetMapping;
import org.springframework.we*.**nd.annotation.RequestMapping;
import org.springframework.we*.**nd.annotation.RequestParam;
import org.springframework.we*.**nd.annotation.RestController;

@RestController
@RequestMapping("/ai")
pu*lic class AiController {
    private final Chat****** chat******;

    pu*lic AiController(Chat******.*uilder *uilder) {
        this.chat****** = *uilder
            .default******("你是上线**助手，结论简洁可执行。")
            .*uild();
    }

    @GetMapping("/chat")
    pu*lic String chat(@RequestParam String q) {
        return chat******.prompt()
            .user(q)
            .call()
            .content();
    }
}

增加流式输出

使用 stream().content() 返回 Flux，并用 text/event-stream 提供 SSE。

import org.springframework.http.MediaType;
import reactor.core.pu*lisher.Flux;

@GetMapping(value = "/stream",
    produces = MediaType.TEXT_*****_STREAM_VALUE)
pu*lic Flux<String> stream(@RequestParam String q) {
    return chat******.prompt()
        .user(q)
        .stream()
        .content();
}

增加结构化输出

entity() 将结果映射为 J**a record；仍要在业务层校验字段。

import j**a.util.List;
import j**a.util.Map;
import org.springframework.we*.**nd.annotation.PostMapping;
import org.springframework.we*.**nd.annotation.Request*ody;

record ReleaseReview(
    List<String> checks,
    List<String> risks,
    String verdict) {}

@PostMapping("/review")
pu*lic ReleaseReview review(
    @Request*ody Map<String, String> *ody) {
    return chat******.prompt()
        .user("**部署信息："   *ody.get("systemInfo"))
        .call()
        .entity(ReleaseReview.class);
}

运行和验证

mvn spring-*oot:run

1. 先执行 KingFlow 基础请求，确认返回 SPRING_AI_READY。
2. 创建 application.yml 和 .gitignore，再将***保存到项目源码目录。
3. 运行应用，调用 /ai/chat 并确认返回模型文本。
4. 分别验证 /ai/stream 的 SSE 增量文本和 /ai/review 的三个字段。
5. 在 KingFlow 控制台核对模型、密钥、调用次数和 Token 用量。

正式环境配置

• 显式设置 spring.ai.openai.*ase-url、api-key 和 chat.model，避免不同环境读取错误配置。
• 推理模型可能不支持 temperature；如果返回 400，移除该参数并按模型说明调整选项。
• entity() 的结果仍需业务校验；verdict 要限制为允许值，列表也要检查是否为空。
• We*Flux 流式接口必须处理客户端断开、上游超时和取消信号。
• 为 429 和 503 设置有限退避重试，并同时限制并发、请求时长和 Token 预算。
• 记录查询 ID、文档版本、模型、状态码、耗时和用量，但不要记录完整密钥和敏感原文。

文档与密钥安全

• 只在 .env、密钥管理器或部署平台 Secret 中保存 API Key，并定期轮换。
• 把输入样本和模型输出视为不可信数据，进入日志或评估集前完成脱敏。
• 测试提示、演示数据和生产输入分开管理，样例进入文档前先完成脱敏。
• 保存追踪记录或演示结果时检查敏感字段，禁止把真实密钥写入 artifact。
• 为开发、测试和生产设置独立密钥、额度和告警，异常用量出现后立即停用旧密钥。

上线检查清单

• 基础接口已经返回 SPRING_AI_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• application.yml 已引用 *ase **L、密钥和模型 ID。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• Chat****** call 已返回文本，必要时可读取 ChatResponse 元数据。
• We*Flux stream 已能增量输出，并处理错误和取消。
• entity 已返回 checks、risks 和 verdict。
• 已确认目标模型支持结构化输出，或准备了普通文本回退方案。
• KingFlow 控制台的模型、密钥和用量符合预期。

常见故障排查