# langchainjs-learn

**Repository Path**: FlowerTip/langchainjs-learn

## Basic Information

- **Project Name**: langchainjs-learn
- **Description**: 本仓库记录了使用 LangChain.js 构建 AI 应用的完整学习路径。包含从基础概念到高级实战的代码 Demo（ChatBot、RAG、Agent）及详细教程文档。基于 Node.js，集成魔搭社区 (ModelScope) 与国内大模型，助力开发者快速上手 LLM 应用开发。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://langchainjs-learn.vercel.app
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain.js v1.x 学习项目

> 📅 适用于 LangChain.js v1.x | 🇨🇳 国内模型友好 | 👶 零基础入门

本教程专为**国内学习者**设计，使用**魔搭社区（ModelScope）** 等国内可访问的模型 API，无需 OpenAI 账号。

---

## 🚀 快速开始

### 1. 环境要求

- **Node.js 20+** （推荐 v20 LTS）
- **npm** 或 **pnpm**

```bash
# 检查 Node.js 版本
node -v  # 应该输出 v20.x.x 或更高
```

### 2. 安装依赖

```bash
# 安装所有依赖
npm install

# 或使用 pnpm
pnpm install
```

### 3. 配置 API Key

#### 方式一：魔搭社区（推荐 ⭐）

本教程默认使用 **魔搭社区（ModelScope）**，这是阿里云提供的免费模型平台。

**获取 API Key 步骤：**

1. 访问 [魔搭社区](https://modelscope.cn/)
2. 注册/登录账号（支持支付宝/淘宝登录）
3. 进入 [控制台](https://modelscope.cn/my/profile/)
4. 点击「访问令牌」→「创建新令牌」
5. 复制 API Key（格式：`ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）

**配置方式：**

```bash
# 方式 1：创建 .env 文件（推荐）
cp .env.example .env
# 编辑 .env 文件，填入你的 API Key

# 方式 2：设置环境变量
# Linux/Mac:
export MODELSCOPE_API_KEY="ms-你的 API Key"

# Windows PowerShell:
$env:MODELSCOPE_API_KEY="ms-你的 API Key"
```

#### 方式二：其他国内模型平台

| 平台 | 文档 | 特点 |
|------|------|------|
| **魔搭社区** | [ModelScope](https://modelscope.cn/) | ✅ 免费额度，模型丰富 |
| **百度千帆** | [千帆大模型](https://cloud.baidu.com/product/wenxinworkshop) | 文心一言系列 |
| **阿里百炼** | [阿里云百炼](https://bailian.console.aliyun.com/) | 通义千问系列 |
| **腾讯混元** | [腾讯混元](https://cloud.tencent.com/product/hunyuan) | 腾讯混元大模型 |
| **智谱 AI** | [智谱清言](https://open.bigmodel.cn/) | GLM 系列模型 |

---

## 📦 项目结构

```
lanchain/
├── tutorial/              # 📚 教程文档
│   ├── 01-基础概念.md
│   ├── 02-环境搭建.md
│   ├── 03-模型调用.md
│   ├── ...
│   └── 14-VectorStore（向量存储）.md
├── src/                   # 💻 示例代码
│   ├── config.js          # 配置文件（API Key 管理）
│   ├── minimax-stream.js  # 流式输出示例
│   ├── agent.js           # Agent 示例
│   ├── rag.js             # RAG 示例
│   └── ...
├── test/                  # 🧪 测试代码
├── .env.example           # 环境变量模板
├── package.json           # 项目配置
└── README.md              # 本文件
```

---

## 🎯 可用模型推荐

### 魔搭社区免费模型

| 模型名称 | 说明 | 免费额度 | 推荐场景 |
|---------|------|---------|---------|
| `MiniMax/MiniMax-M2.5` | MiniMax 最新模型 | ✅ 有免费额度 | 通用对话、文本生成 |
| `Qwen/Qwen2.5-72B-Instruct` | 阿里通义千问 | ✅ 有免费额度 | 中文对话、代码生成 |
| `THUDM/chatglm3-6b` | 智谱 ChatGLM3 | ✅ 有免费额度 | 轻量级对话 |
| `01-ai/Yi-34B-Chat` | 零一万物 Yi | ✅ 有免费额度 | 中英文对话 |

### 本教程使用的模型

```javascript
// src/config.js 中的配置
export const MODEL_CONFIG = {
  modelName: "MiniMax/MiniMax-M2.5",  // 可替换为其他模型
  temperature: 0.7,
  configuration: {
    baseURL: "https://api-inference.modelscope.cn/v1",
  },
};
```

### 更换模型

只需修改 `src/config.js` 中的 `modelName`：

```javascript
// 使用通义千问
export const MODEL_CONFIG = {
  modelName: "Qwen/Qwen2.5-72B-Instruct",
  temperature: 0.7,
  configuration: {
    baseURL: "https://api-inference.modelscope.cn/v1",
  },
};
```

---

## 📚 学习路径

### 基础篇（必学）

| 章节 | 主题 | 示例代码 |
|------|------|---------|
| [01](./tutorial/01-基础概念.md) | 基础概念 | - |
| [02](./tutorial/02-环境搭建.md) | 环境搭建 | - |
| [03](./tutorial/03-模型调用.md) | 模型调用 | `src/minimax-stream.js` |
| [04](./tutorial/04-消息类型.md) | 消息类型 | - |
| [05](./tutorial/05-流式输出.md) | 流式输出 | `src/minimax-stream.js` |

### 进阶篇

| 章节 | 主题 | 示例代码 |
|------|------|---------|
| [06](./tutorial/06-Prompt 模板.md) | Prompt 模板 | `src/temple.js` |
| [07](./tutorial/07-输出解析器.md) | 输出解析器 | `src/zod.js` |
| [08](./tutorial/08-链 (Chain).md) | 链 (Chain) | `src/lian.js` |
| [09](./tutorial/09-记忆 (Memory).md) | 记忆 (Memory) | `src/memory.js` |
| [10](./tutorial/10-工具 (Tools).md) | 工具 (Tools) | `src/tool.js` |
| [11](./tutorial/11-Zod 使用说明.md) | Zod 使用说明 | `src/zod.js` |

### 高级篇

| 章节 | 主题 | 示例代码 |
|------|------|---------|
| [12](./tutorial/12-Agent（智能体）.md) | Agent 智能体 | `src/agent.js` |
| [13](./tutorial/13-RAG（检索增强生成）.md) | RAG | `src/rag.js`, `src/memory-rag.js` |
| [14](./tutorial/14-VectorStore（向量存储）.md) | 向量存储 | `src/vector-store.js`, `src/person-knowledge.js` |

---

## 🏃 运行示例

```bash
# 流式输出示例
node src/minimax-stream.js

# Agent 示例
node src/agent.js

# RAG 示例
node src/rag.js

# 工具调用示例
node src/tool.js

# 记忆对话示例
node src/memory.js

# 链式调用示例
node src/lian.js

# 结构化输出示例
node src/zod.js
```

---

## ⚠️ 常见问题

### 1. API Key 无效/额度不足

```
Error: 401 Unauthorized
Error: 429 InsufficientQuotaError
```

**解决方案：**
- 检查 API Key 是否正确（格式：`ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）
- 登录魔搭社区查看剩余额度
- 免费额度用完后需要等待下月重置或充值

### 2. 模型不存在

```
Error: 404 Model not found
```

**解决方案：**
- 检查 `modelName` 是否正确
- 在魔搭社区确认该模型可用
- 模型名称区分大小写

### 3. 网络超时

```
Error: Request timeout
```

**解决方案：**
- 检查网络连接
- 增加超时时间：`configuration.timeout: 120000`
- 使用国内网络环境

### 4. Node.js 版本太低

```
Error: Requires Node.js 20+
```

**解决方案：**
- 升级 Node.js 到 v20 或更高
- 推荐使用 nvm 管理 Node.js 版本

### 5. 找不到模块

```
Error: Cannot find module 'xxx'
```

**解决方案：**
```bash
npm install
```

---

## 💡 学习建议

1. **按顺序学习**：基础篇 → 进阶篇 → 高级篇
2. **动手实践**：每章都有可运行的示例代码
3. **修改参数**：尝试修改 `temperature`、`modelName` 等参数，观察输出变化
4. **理解概念**：LangChain 的核心是"链式组合"思想
5. **善用文档**：遇到问题先查看教程文档

---

## 🔗 更多资源

### 官方文档

- [LangChain.js 官方文档](https://js.langchain.com/)
- [LangGraph 文档](https://langchain-ai.github.io/langgraphjs/)
- [Zod 官方文档](https://zod.dev/)

### 国内资源

- [魔搭社区](https://modelscope.cn/)
- [智谱 AI 开放平台](https://open.bigmodel.cn/)
- [百度千帆大模型](https://cloud.baidu.com/product/wenxinworkshop)

### 社区

- [LangChain 中文社区](https://github.langchain.ac.cn/)
- [知乎 LangChain 话题](https://www.zhihu.com/topic/21225713)

---

## 📄 许可证

MIT License

---

## 🙏 致谢

- [LangChain](https://github.com/langchain-ai/langchainjs) - AI 应用开发框架
- [魔搭社区](https://modelscope.cn/) - 提供免费模型 API
- [Zod](https://github.com/colinhacks/zod) - TypeScript 模式验证库