Qwen1.5-1.8B GPTQ在Node.js后端服务中的集成实战

最近在折腾一些AI应用，发现很多有意思的模型，但怎么把它们变成稳定可靠的服务，让其他应用也能方便地调用，是个挺实际的问题。就拿Qwen1.5-1.8B这个模型来说，它体积小、推理快，特别适合集成到后端服务里，做一些实时的文本生成或者智能问答。

今天我就来聊聊，怎么用Node.js，把这个模型包装成一个标准的RESTful API服务。整个过程不复杂，从环境搭建到接口封装，再到错误处理和日志记录，我会一步步拆开讲清楚。如果你正在做全栈开发，或者想给自己的应用加一点AI能力，这篇文章应该能给你一些直接的参考。

1. 项目准备与环境搭建

在开始写代码之前，我们得先把“舞台”搭好。这里主要分两步：一是确保你的电脑上Node.js环境没问题，二是把项目的基础架子建起来。

1.1 Node.js安装及环境配置

首先，你得有Node.js。如果你还没装，或者不确定版本，可以打开终端（Windows上是命令提示符或PowerShell，Mac或Linux上是Terminal），输入下面这个命令看看：

node --version

如果显示了版本号，比如 v18.x.x 或更高，那就可以跳过了。我推荐用Node.js 18或20的LTS（长期支持）版本，比较稳定。如果没有安装，去Node.js官网下载安装包，一路点下一步就行，没什么坑。

装好Node.js，顺带着npm（Node.js的包管理器）也就有了。同样，可以验证一下：

npm --version

接下来，我们创建一个新的项目目录。找个你喜欢的地方，打开终端，执行：

mkdir qwen-node-api && cd qwen-node-api
npm init -y

这个 npm init -y 命令会快速生成一个 package.json 文件，里面记录了项目的基本信息和依赖。现在，我们的“舞台”地板就铺好了。

1.2 核心依赖安装

我们这个服务，核心是提供一个HTTP API，所以需要一个Web框架。Express和Koa是Node.js里最流行的两个，它们都很轻量、灵活。我这里以Express为例，因为它生态丰富，资料也多，上手更快。如果你更喜欢Koa的洋葱圈模型，转换起来思路也差不多。

在项目根目录下，安装Express和其他一些必要的工具包：

npm install express axios dotenv

简单解释一下这几个包是干嘛的：

• express: 我们的Web框架，用来定义路由、处理请求和响应。
• axios: 一个非常好用的HTTP客户端库。我们的Node.js服务需要去调用Qwen模型提供的API（假设模型已经部署在另一个服务上），axios能帮我们优雅地完成这个“内部通话”。
• dotenv: 用来管理环境变量。像API密钥、模型服务地址这些敏感或易变的信息，我们不应该硬编码在代码里，用这个包从 .env 文件读取就安全多了。

另外，我们还需要一个工具来帮助开发，比如代码一有改动就自动重启服务，这能极大提升效率。安装它：

npm install --save-dev nodemon

装好之后，打开 package.json 文件，找到 scripts 部分，添加一个启动脚本：

{
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon app.js"
  }
}

这样，以后开发时就用 npm run dev 启动，它会监听文件变化自动重启；正式上线时用 npm start。

2. 构建基础API服务框架

环境齐备，现在可以动手搭建服务的骨架了。我们先创建一个最简单的Express应用，然后规划好API的路由。

2.1 创建Express应用入口

在项目根目录下，新建一个 app.js 文件，这是我们的应用主入口。写入以下代码：

// app.js
require(‘dotenv’).config(); // 加载环境变量
const express = require(‘express’);
const app = express();
const port = process.env.PORT || 3000; // 从环境变量读取端口，默认3000

// 中间件：解析JSON格式的请求体
app.use(express.json());

// 一个简单的根路由，用于健康检查
app.get(‘/’, (req, res) => {
  res.json({ message: ‘Qwen1.5-1.8B API 服务运行正常’, status: ‘ok’ });
});

// 在这里，我们稍后会添加模型相关的路由

// 启动服务
app.listen(port, () => {
  console.log(`🚀 服务已启动，监听端口: ${port}`);
});

这段代码做了几件事：

1. 加载环境变量配置。
2. 创建Express实例。
3. 使用 express.json() 中间件，这样我们的API才能接收客户端发来的JSON数据。
4. 定义了一个根路由 /，访问它返回一个健康状态信息，这在部署后检查服务是否存活很有用。
5. 最后，让服务在指定端口上监听。

现在，在终端运行 npm run dev，你应该能看到启动成功的日志。打开浏览器，访问 http://localhost:3000，就能看到返回的JSON消息了。一个最基础的Web服务就跑起来了。

2.2 设计模型API路由

接下来，我们要设计提供给外部调用的核心接口。根据场景，我们至少需要两个：

1. 文本生成：给定一段提示词（prompt），让模型续写或创作。
2. 智能问答：模拟一个对话回合，根据用户问题和历史对话，给出回答。

在 app.js 里，根路由后面，我们先定义好路由路径（具体的处理逻辑我们放到下一步）：

// app.js (接上文)
const modelRouter = require(‘./routes/model’); // 引入专门的路由模块
app.use(‘/api/v1’, modelRouter); // 所有模型API挂载到 /api/v1 路径下

这样做的好处是代码结构清晰，把路由定义和处理函数分离开。现在，我们需要创建 routes 目录和 model.js 文件。

mkdir routes
touch routes/model.js

在 routes/model.js 中，我们先搭建路由框架：

// routes/model.js
const express = require(‘express’);
const router = express.Router();
const modelController = require(‘../controllers/modelController’); // 引入控制器

// POST /api/v1/generate - 文本生成
router.post(‘/generate’, modelController.generateText);

// POST /api/v1/chat - 智能问答
router.post(‘/chat’, modelController.chatCompletion);

module.exports = router;

这里，我们把具体的业务逻辑委托给了 modelController，这是MVC模式中“控制器”的角色，负责处理请求、调用模型、返回响应。接下来我们就去实现它。

3. 集成Qwen模型调用逻辑

这是最核心的一步，我们要在Node.js服务里，去和Qwen1.5-1.8B GPTQ模型“对话”。这里假设你已经通过某种方式（比如使用Ollama、Xinference，或直接部署了vLLM等推理服务）将模型启动成了一个提供HTTP API的服务，地址是 http://your-model-server:port。

3.1 配置模型服务连接

首先，在项目根目录创建 .env 文件，用来存放配置：

MODEL_API_BASE_URL=http://localhost:11434 # 假设你的模型服务地址
MODEL_NAME=qwen1.5-1.8b # 模型名称
API_TIMEOUT=60000 # 请求超时时间，单位毫秒，模型推理可能较慢

然后，我们创建 controllers/modelController.js 文件，并开始编写调用逻辑。我们先初始化一个配置好的axios实例，这样以后调用模型API就方便了。

// controllers/modelController.js
const axios = require(‘axios’);

// 创建专用的axios实例，配置基础URL和超时
const modelApiClient = axios.create({
  baseURL: process.env.MODEL_API_BASE_URL,
  timeout: parseInt(process.env.API_TIMEOUT) || 60000,
  headers: {
    ‘Content-Type’: ‘application/json’,
  },
});

3.2 实现文本生成接口

现在，实现 generateText 控制器函数。这个函数需要：

1. 从请求体（req.body）中获取用户发送的提示词（prompt）。
2. 构造模型服务能理解的请求格式。
3. 用 modelApiClient 发起POST请求。
4. 处理响应，把模型生成的结果提取出来，返回给客户端。

// controllers/modelController.js (接上文)
exports.generateText = async (req, res, next) => {
  try {
    const { prompt, max_tokens = 512, temperature = 0.7 } = req.body;

    if (!prompt) {
      return res.status(400).json({ error: ‘请求参数错误：prompt 字段为必填项’ });
    }

    // 构造符合模型API要求的请求体
    const requestBody = {
      model: process.env.MODEL_NAME,
      prompt: prompt,
      stream: false, // 我们先处理非流式响应
      options: {
        num_predict: max_tokens,
        temperature: temperature,
      }
    };

    // 调用模型服务
    const response = await modelApiClient.post(‘/api/generate’, requestBody);
    
    // 从响应中提取生成的文本
    const generatedText = response.data.response;

    // 返回成功响应给客户端
    res.json({
      success: true,
      data: {
        prompt: prompt,
        generated_text: generatedText,
        usage: response.data.total_duration ? { total_duration: response.data.total_duration } : {}
      }
    });

  } catch (error) {
    // 错误交给统一的错误处理中间件
    next(error);
  }
};

3.3 实现智能问答接口

问答接口（chatCompletion）稍微复杂一点，因为它通常需要维护一个对话历史（messages）。我们假设请求体里会传递一个消息数组。

// controllers/modelController.js (接上文)
exports.chatCompletion = async (req, res, next) => {
  try {
    const { messages, max_tokens = 512, temperature = 0.8 } = req.body;

    if (!Array.isArray(messages) || messages.length === 0) {
      return res.status(400).json({ error: ‘请求参数错误：messages 必须是一个非空数组’ });
    }

    // 构造请求体，格式需适配你的模型服务
    const requestBody = {
      model: process.env.MODEL_NAME,
      messages: messages, // 格式如 [{ role: ‘user’, content: ‘你好’ }]
      stream: false,
      options: {
        num_predict: max_tokens,
        temperature: temperature,
      }
    };

    const response = await modelApiClient.post(‘/api/chat’, requestBody);
    
    // 假设响应中，最后一条消息是模型的回复
    const assistantMessage = response.data.message;

    res.json({
      success: true,
      data: {
        message: assistantMessage,
        usage: response.data.total_duration ? { total_duration: response.data.total_duration } : {}
      }
    });

  } catch (error) {
    next(error);
  }
};

请注意：上面代码中的请求路径（/api/generate, /api/chat）和请求/响应体格式（response.data.response, response.data.message）是示例。你需要根据你实际部署的模型服务（如Ollama、vLLM等）的API文档进行调整。这是集成过程中最关键的一步——对齐接口协议。

4. 增强服务的健壮性与可观测性

一个只能跑通happy path的服务是不合格的。我们需要处理各种意外情况，并且知道服务内部发生了什么。

4.1 全局错误处理中间件

在Express中，中间件是处理请求的管道。我们可以在所有路由之后，添加一个“错误处理中间件”，它专门捕获前面环节抛出的错误，并返回结构化的错误信息，避免服务崩溃或返回难以理解的堆栈信息。

在 app.js 文件的末尾，启动服务之前，添加这个中间件：

// app.js (接上文，在 app.listen 之前)

// 全局错误处理中间件
app.use((err, req, res, next) => {
  console.error(‘[全局错误]’, err);

  // 判断错误类型，返回相应的HTTP状态码和消息
  let statusCode = 500;
  let message = ‘服务器内部错误’;

  if (err.response) {
    // 这是来自axios的错误，即模型服务调用失败
    statusCode = err.response.status || 502;
    message = `模型服务调用失败: ${err.response.statusText}`;
  } else if (err.request) {
    // 请求发出但没有收到响应（如网络超时）
    statusCode = 504;
    message = ‘模型服务请求超时或无响应’;
  } else if (err.code === ‘ECONNREFUSED’) {
    // 连接被拒绝，通常是模型服务没启动
    statusCode = 503;
    message = ‘无法连接到模型服务，请检查服务是否已启动’;
  }

  res.status(statusCode).json({
    success: false,
    error: {
      code: statusCode,
      message: message,
      // 开发环境下可以返回详细错误，生产环境应屏蔽
      detail: process.env.NODE_ENV === ‘development’ ? err.message : undefined
    }
  });
});

4.2 集成日志记录

日志是我们的“眼睛”。我们不仅要在出错时记录，在正常处理请求时，记录下谁、什么时候、访问了什么、花了多长时间，对于监控和调试至关重要。这里我们用Node.js自带的 console 简单演示，生产环境可以考虑 winston 或 pino 这类更专业的库。

我们可以创建一个简单的日志中间件，放在路由之前：

// app.js (接上文，在 app.use(express.json()) 之后，路由之前)

// 请求日志中间件
app.use((req, res, next) => {
  const start = Date.now();
  const originalSend = res.send;

  // 劫持res.send方法，以便在响应完成后记录日志
  res.send = function (body) {
    const duration = Date.now() - start;
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.originalUrl} - ${res.statusCode} - ${duration}ms`);
    originalSend.call(this, body);
  };

  next();
});

同时，修改一下控制器，在关键步骤也打点日志：

// controllers/modelController.js (在generateText函数内，调用模型前)
console.log(`[INFO] 开始处理生成请求，prompt长度: ${prompt.length}, 参数: max_tokens=${max_tokens}`);

// 在chatCompletion函数内，调用模型前
console.log(`[INFO] 开始处理对话请求，消息数: ${messages.length}`);

5. 测试、运行与后续思考

代码写完了，我们得验证它是否按预期工作。

5.1 使用工具测试API

首先，确保你的Qwen模型服务已经启动并运行在 MODEL_API_BASE_URL 指定的地址上。然后，在项目终端运行 npm run dev 启动我们的Node.js API服务。

现在，你可以用任何喜欢的工具来测试，比如 curl 或者图形化的Postman、Insomnia。

测试文本生成接口：

curl -X POST http://localhost:3000/api/v1/generate \
  -H “Content-Type: application/json” \
  -d ‘{
    “prompt”: “请用一段话介绍Node.js的特点：”,
    “max_tokens”: 150
  }’

测试智能问答接口：

curl -X POST http://localhost:3000/api/v1/chat \
  -H “Content-Type: application/json” \
  -d ‘{
    “messages”: [
      { “role”: “user”, “content”: “JavaScript和Python，哪个更适合初学者？” }
    ]
  }’

观察终端输出的日志，以及API返回的JSON结果。如果一切顺利，你应该能看到模型生成的文本被成功返回。

5.2 项目运行与部署

本地开发测试通过后，就可以考虑部署了。部署到服务器时，有几点需要注意：

1. 进程管理：不要直接用 node app.js，进程挂了不会自动重启。推荐使用 pm2 这样的进程守护工具。

   npm install -g pm2
   pm2 start app.js --name “qwen-api”
   

2. 环境变量：在服务器上正确设置 .env 文件，或者使用服务器平台提供的环境变量配置功能。
3. 反向代理：通常我们不会让Node.js服务直接对外暴露端口，而是用Nginx或Caddy这样的反向代理在前面做一层转发，处理SSL、负载均衡、静态文件等。

6. 写在最后

走完这一遍，你会发现把一个AI模型集成到Node.js后端服务里，本质上和集成其他任何第三方HTTP服务（比如支付接口、短信接口）没有太大区别。核心思路就是：封装、适配、健壮。

封装，是指我们把对模型API的调用细节隐藏在自己的服务层后面，对外提供更简洁、更符合业务需求的接口。适配，是要仔细阅读模型服务的API文档，确保请求格式和响应解析正确无误。健壮，则是通过错误处理、日志、超时控制等手段，让这个服务不至于因为模型服务的暂时波动而彻底崩溃。

我这次用Express演示，如果你用Koa或者Fastify，架构思路是相通的。代码里还有一些可以优化的地方，比如给请求加上频率限制（rate limiting）、对输入输出做更严格的验证、或者把对话历史存储到数据库里实现多轮会话。这些都可以根据你的实际项目需求慢慢加上去。

希望这个实战分享能帮你绕过一些初期的坑。动手试一下，把这个服务跑起来，你会对如何在后端驾驭AI模型有更实在的感觉。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。