# AS-RAG-AI

**Repository Path**: was666/as-rag-ai

## Basic Information

- **Project Name**: AS-RAG-AI
- **Description**: Node + LangChain RAG知识库聊天机器人（火山方舟 + 硅基流动免费版）
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Node.js + LangChain RAG 知识库问答服务（火山方舟 + 硅基流动免费版）

**标签：#LangChain #RAG #Node.js #Koa2 #HTTP接口 #火山方舟 #硅基流动 #知识库AI**

## 🚀 前言

大部分 RAG 要么依赖笨重的向量数据库（Chroma/Pinecone），要么代码老旧、LangChain 版本错乱，极易出现依赖报错、向量库兼容、接口超时等问题。

这是一款**零第三方向量库、纯 Node.js 运行、双模型分离架构**的 RAG 知识库问答 HTTP 服务，基于 Koa2 对外提供接口，核心亮点：

- ✅ **完全免费**：火山方舟每日免费 LLM + 硅基流动永久免费 Embedding

- ✅ **零依赖向量库**：手写内存向量检索，避开 LangChain 版本坑

- ✅ **双模问答**：优先知识库检索，无数据自动切换 AI 通用知识

- ✅ **HTTP 接口服务**：Koa2 提供健康检查、RAG 问答、文档上传三个接口

- ✅ **文档动态入库**：上传 `.txt/.md` 文件后自动重建向量索引，无需重启

- ✅ **长文本提速**：火山 Fast 低延迟推理、上下文裁剪、120 秒超时保护

- ✅ **会话记忆隔离**：通过 `sessionId` 区分不同调用方的多轮对话上下文

## 🎯 整体架构设计

### 1. 技术栈拆分

| 模块 | 服务厂商 | 模型/框架 | 计费规则 | 作用 |
|---|---|---|---|---|
| 对话大模型 | 火山方舟 | doubao-seed-lite | 每日 50 万 Token 免费 | 多轮对话、RAG 答案生成 |
| 嵌入模型 | 硅基流动 | BAAI/bge-large-zh-v1.5 | 永久免费 | 文档向量化、相似度检索 |
| Web 框架 | Koa2 | 3.x | 开源免费 | HTTP 接口、文件上传 |
| 运行环境 | Node.js | 18+ | 本地运行 | 程序主体、文件解析、向量计算 |
| 核心框架 | LangChain 1.x | 最新稳定版 | 开源免费 | 链路编排、记忆管理、Prompt 管理 |

### 2. 核心执行链路

```plain
客户端 HTTP 请求 → Koa2 路由接收 → sessionId 会话记忆 →
RunnablePassthrough（保留原输入）→ 子链 RAG 检索（向量化+余弦匹配）→
拼接参考文档 Prompt → 火山 LLM 推理 → JSON 响应返回答案
```

### 3. 双模问答逻辑（核心亮点）

- **模式 1｜知识库优先**：检索到相关文档 → 仅基于文档回答，强制标注来源

- **模式 2｜通用 AI 回答**：无匹配文档 → 自动切换模型内置知识，并提示用户无本地资料

## ⚙️ 前置准备

### 1. 火山方舟（LLM 对话）

1. 注册火山引擎账号，进入【方舟大模型服务平台】

2. 实名认证后，获取 `VOLC_API_KEY`

3. 部署免费模型：`doubao-seed-2-0-lite`（每日 50 万免费 Token）

4. 获取模型端点 ID、官方 BaseURL

### 2. 硅基流动（Embedding 向量）

1. 注册硅基流动账号，实名认证

2. 获取 `SILICONFLOW_API_KEY`

3. 内置免费模型：`BAAI/bge-large-zh-v1.5` 永久免费向量化

### 3. 项目初始化

```bash
pnpm install
```

## 📁 项目目录结构

```plain
as-rag-ai/
├── .env                # 密钥配置文件（自行创建）
├── index.js            # 服务主程序源码
├── package.json        # 依赖声明
└── docs/               # 知识库目录（启动时自动加载，不存在则纯AI模式）
    ├── 教程.md
    └── 笔记.txt
```

## 🔧 配置文件 .env

```env
# 火山方舟 LLM 配置
VOLC_API_KEY=你的火山方舟API密钥
VOLC_MODEL=你的模型端点ID
VOLC_BASE_URL=https://ark.cn-beijing.volces.com/api/v3

# 硅基流动 Embedding 配置
SILICONFLOW_API_KEY=你的硅基流动API密钥

# 服务端口（可选，默认 3000）
PORT=3000
```

## ▶️ 启动服务

1. （可选）项目根目录新建 `docs` 文件夹，放入任意 `.txt/.md` 知识库文档，启动时自动加载

2. 填写 `.env` 中的两类 API 密钥

3. 启动服务：

```bash
node index.js
```

启动成功后控制台输出：

```plain
🌐 RAG 接口服务已启动: http://localhost:3000
   GET  /health
   POST /api/rag     — RAG知识库问答 {question, sessionId?}
   POST /api/upload  — 上传文档文件入库 (multipart/form-data, 字段名file)
🚀 RAG知识库问答服务启动成功，Ctrl+C 停止服务
```

停止服务：`Ctrl+C`

## 📡 接口文档

服务默认监听 `http://localhost:3000`，所有响应均为 JSON 格式，失败时返回 `{ "success": false, "error": "错误信息" }`。

### 1. GET /health — 健康检查

探测服务是否存活。

```bash
curl http://localhost:3000/health
```

响应示例：

```json
{
  "success": true,
  "message": "RAG service is running"
}
```

### 2. POST /api/rag — RAG 知识库问答

提交问题，服务自动执行知识库检索并生成回答；相同 `sessionId` 的请求共享多轮对话记忆。

**请求体（application/json）：**

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| question | string | 是 | 用户提问 |
| sessionId | string | 否 | 会话 ID，不传时默认为 `default` |

```bash
curl -X POST http://localhost:3000/api/rag \
  -H "Content-Type: application/json" \
  -d '{"question": "如何部署模型？", "sessionId": "user-001"}'
```

响应示例：

```json
{
  "success": true,
  "answer": "……（来源：教程.md）",
  "sessionId": "user-001"
}
```

### 3. POST /api/upload — 上传文档入库

上传 `.txt/.md` 文件到 `docs` 目录，保存成功后自动重新加载全部文档并重建向量索引，无需重启服务。

**请求体（multipart/form-data）：**

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | File | 是 | 知识库文件，仅支持 `.txt` / `.md` |

```bash
curl -X POST http://localhost:3000/api/upload \
  -F "file=@/本地路径/笔记.txt"
```

响应示例：

```json
{
  "success": true,
  "message": "文档 笔记.txt 已上传并入库",
  "filename": "笔记.txt",
  "size": 1024,
  "path": "docs/笔记.txt"
}
```

## 🔥 核心技术亮点解析

### 1. 为什么不用 Chroma/Pinecone 向量库？

官方向量库存在**版本兼容、二进制编译、跨平台报错**三大问题。手写内存向量检索，基于余弦相似度计算，功能完全对标 `MemoryVectorStore`，零额外安装、开箱即用。

### 2. 双模型免费架构精髓

- 火山方舟 LLM：每日免费 Token，国内低延迟，支持 Fast 推理加速长文本

- 硅基流动 Embedding：BGE 中文向量模型永久免费，RAG 零成本构建知识库

### 3. 解决「AI 思考很久/超时」问题

- 开启火山 `serviceTier:fast` 低延迟算力池

- 限制单文档 700 字符、召回 Top2 文档，压缩上下文 Token

- RAG 接口 120 秒超时保护，异常直接返回错误信息

- 关闭模型深度思考、降低随机性，加快推理速度

### 4. RunnableSequence + RunnablePassthrough 核心原理

通过 `RunnablePassthrough.assign` 保留原始用户输入，同时执行 RAG 检索生成上下文，解决 LangChain 管道数据流覆盖问题；使用数组式 `RunnableSequence.from` 编排链路，retriever 以闭包变量引用，上传文档重建索引后即时生效。

### 5. 会话记忆隔离

问答接口通过 `sessionId` 标识调用方，对话历史保存在进程内存中（服务重启后清空），适合轻量级多轮问答场景。

## 🐛 常见问题排查

1. **接口请求超时**：减少 docs 文档数量、降低 chunkSize、缩小上传文件体积、检查网络

2. **检索不到文档**：检查文件编码为 UTF-8、后缀是否为 txt/md、相似度阈值（默认 0.3）是否过高

3. **模型报错**：核对 API 密钥、模型端点 ID、账号是否有额度/实名认证

4. **上传后问答无变化**：确认返回 `success: true` 且控制台已打印「向量生成完成，知识库就绪」，索引重建完成前的请求可能仍命中旧索引

5. **端口被占用**：在 `.env` 中修改 `PORT`，或释放被占用的 3000 端口