大模型应用开发 / 系统课时

使用 JavaScript SDK

使用 JavaScript SDK

学习目标

完成本课后,你将能够:

  • 安装并使用官方 ollama JavaScript 库
  • 在 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:模拟客户端断开

任务目标:处理取消与清理。输入或初始条件:流式请求正在进行。实现要求:触发取消并终止迭代。验收条件:残缺消息标记为取消,不进入正式历史。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 JavaScript SDK

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通