常用接入术语

接入架构

接入优势

• generateText 适合一次性生成，streamText 适合聊天和实时界面，两者共享同一个模型实例。
• createOpenAICompati*le 可以显式设置 *ase **L 与密钥，避免把兼容端点误当成其他协议。
• Output.o*ject 与 Zod 结合后可获得类型安全的对象，并在运行时验证字段形态。
• AI SDK 的模型抽象让提示、模型和输出处理保持分离，便于测试与替换。
• KingFlow 控制台集中管理模型、密钥和用量，便于隔离不同环境。

开始前的准备

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

创建 Vercel AI SDK 测试项目

mkdir kingflow-ai-sdk-demo
cd kingflow-ai-sdk-demo
pnpm init
pnpm add ai @ai-sdk/openai-compati*le zod dotenv
pnpm add -D tsx typescript @types/node

验证 KingFlow 基础接口

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

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": "只回复 AI_SDK_READY"}],
    "stream": false
  }'

配置环境变量

KINGFLOW_*ASE_**L=https://api.**nju**shen.com/v1
KINGFLOW_API_KEY=sk-你的密钥
KINGFLOW_MODEL=<KingFlow控制台中的完整模型ID>

.env
node_modules/
dist/
.vercel/

编写文本生成示例

使用 createOpenAICompati*le 连接 KingFlow，再通过 generateText 生成文本。

import "dotenv/config";
import { createOpenAICompati*le } from "@ai-sdk/openai-compati*le";
import { generateText, streamText, Output } from "ai";
import { z } from "zod";

const kingflow = createOpenAICompati*le({
  name: "kingflow",
  *ase**L: process.env.KINGFLOW_*ASE_**L!,
  apiKey: process.env.KINGFLOW_API_KEY!,
});

const model = kingflow(process.env.KINGFLOW_MODEL!);
const { text, usage, finishReason } = await generateText({
  model,
  system: "你是上线**助手，结论必须简洁可执行。",
  prompt: "只回复 AI_SDK_CONNECTED，然后给出两项上线检查。",
  temperature: 0.2,
  **xOutputTokens: 600,
  a*ortSignal: A*ortSignal.timeout(60_000),
});

console.log(text);
console.log({ usage, finishReason });

增加流式输出

生产代码要处理超时、客户端取消和 onError。

const result = streamText({
  model,
  prompt: "用三点说明 API 中转服务的上线验收方法。",
  **xOutputTokens: 600,
  a*ortSignal: A*ortSignal.timeout(60_000),
  onError({ error }) {
    console.error("stream error", error);
  },
});

for await (const part of result.textStream) {
  process.stdout.write(part);
}

增加结构化输出

Output.o*ject 与 Zod 会验证返回对象；若目标模型不支持，应退回普通文本并自行解析。

const { output } = await generateText({
  model,
  output: Output.o*ject({
    sche**: z.o*ject({
      checks: z.array(z.string()),
      risks: z.array(z.string()),
      verdict: z.enum(["pass", "review"]),
    }),
  }),
  prompt: "**：密钥已隔离，额度已设置，尚未配置 429 重试。",
});

console.log(output);

运行和验证

pnpm tsx src/**in.ts

1. 先执行 KingFlow 基础请求，确认返回 AI_SDK_READY。
2. 创建 .env 和 .gitignore，再将基础示例保存为 src/**in.ts。
3. 运行程序，确认 generateText 返回 AI_SDK_CONNECTED。
4. 分别验证 streamText 的增量文本和 Output.o*ject 的三个字段。
5. 在 KingFlow 控制台核对模型、密钥、调用次数和 Token 用量。

正式环境配置

• 使用 @ai-sdk/openai-compati*le，显式固定 OpenAI 兼容 *ase **L 与 *earer 密钥。
• 结构化输出依赖目标模型能力；不支持时改用 generateText 返回普通文本，再在应用层解析和校验。
• A*ortSignal.timeout 只限制单次请求；生产环境还要设置并发、队列和总体任务时限。
• 流式响应必须处理客户端断开与 onError，不能只依赖正常结束路径。
• 为 429 和 503 设置有限退避重试，并同时限制并发、请求时长和 Token 预算。
• 记录查询 ID、文档版本、模型、状态码、耗时和用量，但不要记录完整密钥和敏感原文。

文档与密钥安全

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

上线检查清单

• 基础接口已经返回 AI_SDK_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• createOpenAICompati*le 已设置 *ase **L、密钥和模型 ID。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• generateText 已返回文本、结束原因和可用的 usage 数据。
• streamText 已能增量输出，并处理错误和取消。
• Output.o*ject 已返回 checks、risks 和 verdict。
• 已确认目标模型支持结构化输出，或准备了普通文本回退方案。
• KingFlow 控制台的模型、密钥和用量符合预期。

常见故障排查