大模型应用开发 / 系统课时
使用 JavaScript SDK
使用 JavaScript SDK
学习目标
完成本课后,你将能够:
- 安装并使用官方
ollamaJavaScript 库- 在 Node.js 中调用生成和对话接口
- 使用异步迭代处理流式响应
- 正确处理连接、模型和取消错误
创建 Node.js 项目
执行:
bash
mkdir ollama-js-demo
cd ollama-js-demo
npm init -y
npm install ollama预期输出中应包含:
text
added <COUNT> packages
found 0 vulnerabilities依赖数量和审计结果可能变化。出现安全提示时应检查具体依赖,不要忽略。
单轮生成
创建 generate.mjs:
js
import ollama from "ollama";
try {
const response = await ollama.generate({
model: "gemma3:1b",
prompt: "用两句话解释 JavaScript SDK 的用途。",
options: {
temperature: 0,
num_predict: 100,
},
});
console.log(response.response.trim());
console.log(`done=${response.done}`);
} catch (error) {
console.error("调用失败:", error.message);
process.exitCode = 1;
}运行:
bash
node generate.mjs预期输出结构:
text
<MODEL_RESPONSE>
done=true对话调用
创建 chat.mjs:
js
import ollama from "ollama";
const response = await ollama.chat({
model: "gemma3:1b",
messages: [
{
role: "system",
content: "你是技术助教,回答不超过 80 字。",
},
{
role: "user",
content: "REST API 和 SDK 的关系是什么?",
},
],
options: {
temperature: 0,
},
});
console.log(response.message.content.trim());运行:
bash
node chat.mjs预期输出:
text
<MODEL_RESPONSE>流式响应
创建 stream.mjs:
js
import ollama from "ollama";
const stream = await ollama.chat({
model: "gemma3:1b",
messages: [
{
role: "user",
content: "用四个要点说明 Node.js 流式处理原则。",
},
],
stream: true,
});
for await (const part of stream) {
const content = part.message?.content ?? "";
if (content) {
process.stdout.write(content);
}
}
process.stdout.write("\n");运行:
bash
node stream.mjs预期输出:
text
<INCREMENTAL_MODEL_RESPONSE>自定义客户端
创建 remote-client.mjs:
js
import { Ollama } from "ollama";
const client = new Ollama({
host: "http://<OLLAMA_HOST>:11434",
headers: {
"X-Client-Name": "anystack-tutorial",
},
});
const response = await client.chat({
model: "gemma3:1b",
messages: [{ role: "user", content: "只回答:connected" }],
});
console.log(response.message.content.trim());预期输出:
text
<MODEL_RESPONSE>远程地址应由反向代理提供认证和 TLS,不应把默认服务直接暴露到公网。
取消流式请求
官方客户端的流对象支持中止时,可以在达到条件后调用中止方法。具体 API 应以当前库类型定义和 README 为准。通用应用逻辑应确保:
- 用户点击停止时取消底层请求。
- 退出异步迭代。
- 把消息标记为
cancelled。 - 不把残缺工具调用写入会话。
- 记录已接收字符数和取消原因。
不要只停止页面渲染而继续在后台消耗模型资源。
错误处理
创建 errors.mjs:
js
import ollama from "ollama";
try {
const response = await ollama.chat({
model: "model-that-does-not-exist",
messages: [{ role: "user", content: "你好" }],
});
console.log(response.message.content);
} catch (error) {
console.error(`name=${error.name}`);
console.error(`message=${error.message}`);
process.exitCode = 1;
}运行:
bash
node errors.mjs预期输出结构:
text
name=<ERROR_NAME>
message=<ERROR_MESSAGE>错误类型和文本随库版本变化,程序不应依赖完整错误字符串做业务判断。
工程注意事项
Node.js 服务接入时还应设置:
- 服务端请求超时
- 每用户并发限制
- 流式连接断开处理
- 输出大小限制
- 日志脱敏
- 模型名称白名单
- 进程关闭时的连接清理
- 前端与后端职责边界
浏览器直接访问 Ollama 会涉及跨域和安全问题,通常应由业务后端代理调用。
本课练习
练习 1:封装 Node 客户端
任务目标:统一调用配置。输入或初始条件:已安装 ollama 包。实现要求:封装 chat、stream 和错误转换。验收条件:模型名由白名单控制。
练习 2:实现流式命令行
任务目标:练习异步迭代。输入或初始条件:准备一个长回答提示词。实现要求:逐块输出并统计总字符数。验收条件:最终换行正常,异常时退出码非零。
练习 3:模拟客户端断开
任务目标:处理取消与清理。输入或初始条件:流式请求正在进行。实现要求:触发取消并终止迭代。验收条件:残缺消息标记为取消,不进入正式历史。
按自己的节奏,确认真正理解。