写了十年传统 CRUD 业务，去年才转型做 AI 应用开发。
刚上手以为调用大模型接口和普通 HTTP 查询一样，几行代码本地跑通就算完工。直到多次线上故障才明白，极简测试代码放到生产环境隐患极多。

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: "sk-xxx" });
const response = await client.chat.completions.create({ model: "deepseek-chat", messages: [{ role: "user", content: "你好" }] })

这段代码缺少超时、重试、输出长度限制、限流处理，线上流量波动极易引发服务异常、成本失控。
这篇不聊虚的，全是我踩出来的干货，拆三块说：调参控模型、选合适模型平台、封装能扛住线上的调用逻辑。

别贪图省事绑定厂商私有 SDK，认准 OpenAI 兼容协议

刚转型阶段图省事，分别接入各厂商专属 SDK，不同服务商传参、报错结构、返回字段完全不统一。后续多模型并行测试时，维护成本大幅上涨。
目前行业通用兼容规范，和 TCP/IP 协议作用类似，是通用对接标准。只要服务商支持该规范，切换模型仅更换密钥与服务地址，业务代码无需大规模重构。
基础通用模板如下，服务商地址按需填入环境变量即可：

// 对接DeepSeek
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_KEY,
baseURL: "https://api.deepseek.com"
});
// 切换阿里通义千问
const client = new OpenAI({
apiKey: process.env.QWEN_KEY,
baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
});
// 切字节豆包火山方舟
const client = new OpenAI({
apiKey: process.env.DOUBAO_KEY,
baseURL: "https://ark.cn-beijing.volces.com/api/v3"
});

LangChain、LlamaIndex 等主流 AI 工具库均原生适配这套标准。如果项目初期选用厂商私有 SDK，后期多模型迭代会产生大量适配工作量。后面多模型迭代全是还债，纯纯给自己添堵。

一堆 API 参数不用全啃，吃透四个就能拿捏模型输出

打开创建对话的方法，密密麻麻参数堆一块，刚转行看得头都大。
刨除冷门微调参数，日常业务只需要盯四个核心值，剩下默认不动就行。

const completion = await openai.chat.completions.create({
  model:'deepseek-chat',
  messages:[{ role:'user', content: prompt }],
  temperature:0.7,
  max_tokens:500,
  top_p:0.9,
  seed:42,
  stream:false,
  frequency_penalty:0.0,
  presence_penalty:0.0,
})

Temperature，模型脑洞调节旋钮

数值区间 0~1+，数值越低输出确定性越强。

• 固定 0：每次生成结果完全一致，适合代码编写、结构化 JSON 提取、数学运算等对输出稳定有要求的场景
• 0.7~0.9：平衡稳定与发散，文案、角色扮演、创意类内容适用
• 大于 1：文本发散度极高，正式线上业务极少使用

// 生成JS快排，温度置0保证代码稳定无变体
const resCode = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "用JS实现快速排序" }],
temperature: 0
});
// 科幻短篇创作，放开想象力
const resNovel = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "写一段科幻小说开篇" }],
temperature: 0.8
});

写代码就把旋钮拧死，让模型像严谨后端；写故事放宽限制，随便发散。

Top_p，动态词汇筛选器，千万别和温度一起调

核采样逻辑，从高概率字词累加，凑够设定数值就截断候选词池。

举个例子，下一词概率：好 50%、很好 30%、不错 15%、棒 5%。top_p 设 0.8，只会从前两个词里选。

Top_p和 top-k 完全两码事，top-k 固定截取前 N 个词，top_p 会跟着概率分布动态调整候选数量。 踩过巨坑，同时修改 temperature 和 top_p，模型采样逻辑互相冲突，回答一会正常一会离谱。 绝大多数场景 top_p 固定 1.0，只改动 temperature。只有需要严格收缩词汇范围的特殊场景，才单独调整它。

// 规范写法，仅调节温度
await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "你好" }],
temperature: 0.7,
top_p: 1.0
});
// 反面踩坑示范，双随机参数同时改动
await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "你好" }],
temperature: 0.7,
top_p: 0.9
});

Max Tokens，防止账单爆炸的保命开关

不少刚转 AI 的同行搞混，这个参数只管输出 token，输入文本不受限制。
没设上限的血泪经历：用户一段模糊提问，模型循环复读一整晚，第二天账单直接多出几千块开销。

线上必须设置固定上限，防止模型无限循环重复文本，造成 token 消耗异常。

• 简短问答类：100 以内
• 常规文章生成：4096
• 全局兜底阈值：65535

Seed，调试阶段专属控制变量

调 prompt 的时候，每次输出都不一样，根本分不清是提示词优化有用，还是随机采样带来的变化。
固定同一个 seed，相同入参、相同温度，模型返回内容完全复刻。

// 调试阶段锁定种子，方便对比不同prompt效果
const res1 = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "写产品介绍文案" }],
temperature: 0.7,
seed: 12345
});
// 同参数同种子，输出一字不差
const res2 = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: "写产品介绍文案" }],
temperature: 0.7,
seed: 12345
});

线上环境直接删掉 seed，保留回答多样性，用户交互体验更好。

各场景参数速查表，复制就能用

使用场景	Temperature	Top_p	Max Tokens	Seed
代码生成	0	1.0	2048	可选固定
JSON 结构化提取	0	1.0	1024	不设置
数学计算推理	0	1.0	512	可选固定
营销文案创作	0.7-0.9	1.0	4096	移除
角色对话交互	0.8-1.0	按需	按需	移除
Prompt 调试优化	0.7	1.0	2048	固定数值

不同模型服务的工程选型客观约束

市面主流模型服务各有技术层面约束，选型需结合并发、上下文长度、测试额度、计费规则综合评估，不存在通用最优方案：

1. 开源聚合类服务：内置大量开源模型，提供基础测试配额，但免费调用存在每分钟请求、token 流量上限，高日活项目需提升服务配额。适合本地多模型对比、内部测试工具。
2. 阿里云模型服务：支持超大上下文规格，配套 RAG、文档解析等配套工具。计费采用阶梯规则，单次输入文本越长单位成本越高，长文档批量任务需提前测算消耗。
3. 字节系模型服务：高并发承载能力较好，长输入文本会触发阶梯涨价，实时 C 端对话场景适配度更高。
4. 腾讯大模型服务：和微信生态工具联动完善，默认并发通道数量有限，高流量业务需扩容通道，附加检索插件会产生额外计费。
5. 独立开源模型官方服务：推理能力表现均衡，但晚间访问高峰期容易出现超时、502 报错，不适合实时前端业务，更适合离线批量任务。
6. 海外模型聚合平台：可统一调用海外大模型，但国内访问存在网络延迟，出海项目可考虑。

选型简易判断逻辑

• 开发测试、多模型对比→硅基流动
• 百万字超长文档、企业 RAG→阿里百炼
• 高并发 C 端实时产品→火山方舟
• 微信小程序 / 公众号→腾讯混元
• 海外出海业务→OpenRouter
• 离线低成本推理→DeepSeek 官方

线上工程兜底封装，CRUD 十年的容错思路套 AI 接口

写传统接口习惯加异常捕获、重试、限流，刚转 AI 时偷懒省略，线上全是事故。
网络波动、服务商临时故障、流量打满限流，都是家常便饭。

指数退避重试，别无脑循环轰炸接口

无限同步重试会给服务商施压，直接加重 429 限流。
用 p-retry 实现间隔递增重试，最多尝试三次，等待 1s→2s→4s，单次最长等待 10 秒。
大模型推理耗时久，超时统一设 120 秒，传统 5 秒 HTTP 超时完全不够用。

import pRetry from 'p-retry';
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: "https://api.deepseek.com",
timeout: 120000
});
async function callLLM(prompt) {
return pRetry(
async () => {
const res = await client.chat.completions.create({
model: "deepseek-chat",
messages: [{ role: "user", content: prompt }]
});
return res.choices[0].message.content;
},
{
retries: 3,
factor: 2,
minTimeout: 1000,
maxTimeout: 10000,
onFailedAttempt: (err) => {
console.log(`第${err.attemptNumber}次调用失败，剩余重试次数${err.retriesLeft}`);
}
}
);
}
// 业务调用
try {
const result = await callLLM("写工具类代码");
console.log(result)
} catch (err) {
console.error("三次重试全部失败", err);
}

SSE 流式输出，解决用户空白等待焦虑

同步全量返回，用户要等五六秒空白页面，大概率直接关掉页面。
逐字流式推送，用户能实时看到输出，等待感知大幅降低。
后端规范配置 SSE 响应头，关闭 Nginx 缓冲，严格遵循data: {json}\n\n标准格式。

// Next后端流式基础逻辑
res.setHeader('Content-Type', 'text/event-stream')
res.setHeader('Cache-Control', 'no-cache')
res.setHeader('Connection', 'keep-alive')
res.setHeader('X-Accel-Buffering', 'no')
const stream = await openai.chat.completions.create({
model: 'deepseek-ai/DeepSeek-V3.2-Exp',
messages: [{ role: 'user', content: prompt }],
temperature: 0.7,
max_tokens: 2000,
stream: true
})
res.write(`data: ${JSON.stringify({ type: 'start', message: '开始生成...' })}\n\n`)
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content || ''
if (content) res.write(`data: ${JSON.stringify({ type: 'chunk', content })}\n\n`)
}
res.write(`data: ${JSON.stringify({ type: 'done', message: '生成完成' })}\n\n`)
res.end()

前端不能直接用 EventSource，仅支持 GET 请求。业务传 prompt 只能 Fetch+ReadableStream 手动拆缓冲区，处理不好会出现文字重复刷屏。

API 密钥绝对不能硬编码进代码

有人踩过大坑，明文 sk 密钥提交 Git，一晚上被恶意调用，上万账单自己兜底。
本地开发用.env.local 存密钥，.gitignore 全局忽略该文件。
区分服务端、客户端环境变量，密钥不加 NEXT_PUBLIC 前缀，防止前端泄露。定期轮换密钥，就算泄露也能快速止损。

# .env.local DEEPSEEK_API_KEY=sk-xxxx DEEPSEEK_BASE_URL=https://api.deepseek.com

// Node项目加载环境变量
import dotenv from 'dotenv';
dotenv.config();
const client = new OpenAI({
apiKey: process.env.DEEPSEEK_API_KEY,
baseURL: process.env.DEEPSEEK_BASE_URL
});

两个高频线上埋雷点，提前规避少背锅

1. Token 成本预估偏差

文字字数不等于 token，各家分词规则不一样，同一段文本消耗 token 差距很大。
上线预估成本预留 20%-30% 缓冲，用 js-tiktoken 提前计算真实消耗，别按汉字数量粗略估算。

import { encoding_for_model } from 'js-tiktoken';
function countTokens(text, model = 'gpt-4') {
const encoding = encoding_for_model(model);
const tokens = encoding.encode(text);
encoding.free();
return tokens.length;
}

成本计算公式：输入 token 数 × 输入单价 + 输出 token 数 × 输出单价，切换模型时两边数值都要重新测算。

2. 429 限流报错处理
所有平台都有 RPM、TPM 限制，免费版阈值极低，流量上涨直接返回 429。
捕获报错读取 Retry-After 头部，等待指定时长再重试，别收到报错立刻重发。
高 QPS 百万用户项目，做多 Key 轮询分摊流量，单密钥触发限流自动切换下一个客户端。

// 多密钥轮询简易封装
class OpenAIClient{
constructor(apiKeys) {
this.clients = apiKeys.map(key=>new OpenAI({
apiKey: key,
baseURL: "https://api.deepseek.com",
timeout:60000
}));
this.currentIndex=0;
}
getNextClient(){
const client=this.clients[this.currentIndex];
this.currentIndex = (this.currentIndex +1) % this.clients.length;
return client;
}
async chat(prompt, maxRetries=3){
let lastError;
for(let i=0;i<maxRetries;i++){
const client = this.getNextClient();
try{
const res = await client.chat.completions.create({
model:"deepseek-chat",
messages: [{ role:"user",content: prompt}]
});
return res.choices[0].message.content;
} catch (err){
lastError= err;
console.log(`当前密钥异常，切换下一个`);
if(err.status===429) await new Promise(res=>setTimeout(res,2000));
}
}
throw new Error(`全部密钥调用失败：${lastError.message}`);
}
}
// 实例化多密钥客户端
const client=new OpenAIClient([
process.env.DEEPSEEK_API_KEY_1,
process.env.DEEPSEEK_API_KEY_2,
process.env.DEEPSEEK_API_KEY_3
]);

落地实操：整合全部逻辑做流式 AI 聊天页面

把上面所有容错、体验、成本逻辑打包，直接丢给 AI 生成完整前后端页面。
开发环境选用硅基流动，模型 deepseekai/DeepSeek-V3.2-Exp，temperature 设 0.8，超时 120 秒，max_tokens 拉满 65535，生产去掉 seed。
后端集成指数重试、SSE 流式推送，前端手动解析流避免文字重复。
每次请求自动统计输入输出 token，底部展示单次调用成本，429 限流自动延迟重试。
整套功能不用后期补容错代码，直接上线能用。

我们在 cursor初学实战项目——待办清单-CSDN博客 基础上，新增AI流聊天功能

提示词：

在首页新增一个 tab【流式AI】，实现一个 AI 聊天功能：

模型调用参考 pages/api/tasks/breakdown.ts ，模型参数配置：温度 0.8、超时 120s、MaxTokens 65535、Seed 注释掉（稍后我会测试开启）；

模型平台选择硅基流动，baseURL 为 https://api.siliconflow.cn/v1 ，模型使用 deepseek-ai/DeepSeek-V3.2-Exp；

封装接口使用 p-retry 进行重试、SSE 流式输出、前端实现逐字输出结果（且不重复）；

每次请求使用 js-tiktoken 计算 token 数和成本（DeepSeek-V3.2 价格：输入 2元/百万tokens、输出 3元/百万tokens）；

遇到 429 错误，根据响应头中的 Retry-After 字段获取对方返回的重试时间进行重试；

碎碎念收尾

写十年 CRUD 总以为接口封装那套逻辑万能，转 AI 才发现大模型藏了一堆独有的线上风险。
参数调优、平台选型、重试限流、流式交互、密钥安全、成本监控，缺任意一块都容易线上翻车。
新手只会跑通 demo，干久了才懂稳定 AI 服务拼的全是兜底逻辑。
把这些坑吃透，再落地几个真实业务，不用羡慕资深 AI 工程师，自己也能独立扛整套应用开发。