大模型前端对接教程：从零跑通流式对话页面
大模型前端对接，核心就三件事：把请求参数拼对、把流式响应解析出来、别把 API Key 暴露在浏览器里。
本文用一个最小可运行页面，带你从零跑通一次对话请求，并给出常见报错的处理方法。
先确认你手里有什么
对接前需要准备三样东西：一个能调用的大模型 API 地址、一个可用的 API Key、一个本地静态页面或前端项目。
如果你还没有 Key，先在模型服务商控制台创建，并记录接口地址和模型名称。
不同服务商的请求路径和模型名不同，以控制台文档为准。
本地调试建议用浏览器直接打开 HTML 文件，或启动一个简单静态服务器：
python3 -m http.server 8080访问 http://127.0.0.1:8080 即可。
注意：如果直接 file:// 打开页面，部分浏览器的跨域请求会受限，建议用上面的本地服务器方式。
最小请求：先跑通非流式对话
先从非流式接口开始，确认地址、Key 和模型名都对。
下面是最小请求示例，参数名以你所用服务商为准：
async function chat() {
const res = await fetch('https://你的接口地址/v1/chat/completions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer 你的API_KEY'
},
body: JSON.stringify({
model: '你的模型名称',
messages: [{ role: 'user', content: '你好，请用一句话介绍自己' }]
})
});
const data = await res.json();
console.log(data.choices[0].message.content);
}
chat();预期结果是控制台打印出模型回复。
如果这一步就报错，先别往下做流式，按后面的报错表逐项检查。
改成流式输出，让页面逐字显示
大模型回复通常较慢，流式输出能明显改善体验。
大多数服务商使用 SSE（Server-Sent Events，服务器推送事件）返回分片数据。
前端用 fetch 读取 response.body，再通过 TextDecoder 解码：
const res = await fetch('/api/chat', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ messages: [{ role: 'user', content: '写一句问候语' }] })
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop();
for (const line of lines) {
if (!line.startsWith('data:')) continue;
const payload = line.slice(5).trim();
if (payload === '[DONE]') continue;
const json = JSON.parse(payload);
const delta = json.choices?.[0]?.delta?.content || '';
document.getElementById('output').textContent += delta;
}
}关键点：buffer 用来处理半行数据，每次按 \n 切分后保留最后一段不完整内容，否则 JSON 解析会偶发失败。
密钥别放前端：加一层代理
把 API Key 写在前端 JS 里，等于公开泄露。
正确做法是前端只请求你自己的后端或反向代理，由服务端注入 Key。
用 Nginx 做一层转发是常见做法：
location /api/chat {
proxy_pass https://你的接口地址/v1/chat/completions;
proxy_set_header Authorization "Bearer 你的API_KEY";
proxy_set_header Content-Type "application/json";
proxy_buffering off;
proxy_cache off;
}proxy_buffering off 对流式输出很关键，否则 Nginx 可能攒够数据才返回，页面看起来像卡住。
改完配置执行 nginx -t 检查语法，再 nginx -s reload 生效。
常见报错怎么查
- 401 Unauthorized：Key 错误、过期或请求头没带上。检查
Authorization拼写和 Bearer 后是否有空格。 - 404 Not Found：接口路径或模型名不对。对照控制台文档核对
/v1/chat/completions是否完整。 - 429 Too Many Requests：触发了频率限制，降低请求频率或检查账户额度。
- 页面一直无输出：先看浏览器 Network 面板请求是否 pending，再检查代理是否开启了缓冲，以及是否被跨域拦截。
- JSON 解析报错：多半是流式分片没拼完整，确认按行缓冲处理，不要直接对每个 chunk 做
JSON.parse。
验证对接是否真正可用
打开页面输入一句话，观察三点：回复是否逐字出现、控制台有无报错、Network 中响应状态是否为 200。
再刷新页面重复一次，确认不是缓存造成的假象。
如果流式正常但内容为空，检查解析字段是否与接口返回结构一致。
对接大模型前端时，先跑通非流式请求再切流式，密钥统一走后端代理，遇到报错优先看状态码和响应体。
按这个顺序排查，大多数对接问题都能在十分钟内定位。
