# LangChain 学习平台（langchain-learning-kit）

> 目标：提供一个**企业级目录结构**和**简洁可运行**的示例系统，用来学习 LangChain 的关键功能：MySQL 配置与持久化、模型管理（可切换 LLM）、知识库管理（向量库 + 元数据）、多轮对话（会话状态）、自定义智能体（Agent）、以及常用运维/安全/测试准备。设计偏教学但架构接近生产可演示性。

------

# 一、总体概览

- 用户 → 前端/CLI → API Server (FastAPI) → 服务层：
  - Auth & UserManager（MySQL）
  - ModelManager（LLM 配置/版本）
  - KnowledgeBaseManager（向量索引 + 文档元数据）
  - ConversationManager（会话/历史）
  - Agent Orchestrator（RAG + 多工具）
  - Jobs / Workers（异步任务：索引、embed、清理）
- 向量存储：FAISS（本地）
- Embeddings：OpenAI
- LLM：OpenAI 
- 持久化：MySQL（元数据、用户、会话索引等） + 本地磁盘或 S3（FAISS 索引快照、文档原文）

------

# 二、技术选型

- 后端框架：FastAPI
- LangChain：核心库 + langchain-community（Vectorstores）
- 向量 DB：FAISS（本地，开发）
- Embeddings/LLM：OpenAI（示例），兼容层支持自托管模型（via ModelManager）
- 异步任务：Celery / RQ（演示可用内置 asyncio）
- 数据库：MySQL（演示使用 SQLAlchemy + Alembic）
- Docker：容器化
- CI：pytest + GitHub Actions
- 配置管理：dotenv / Env vars
- 日志/监控：结构化日志（uvicorn/structlog）、Prometheus（可选）

------

# 三、关键组件说明

## 1. ModelManager（模型管理）

职责：

- 管理可用的 embedding 模型与 LLM（名称、type、endpoint、apikey、可用状态）
- 提供统一接口 `get_embedding_provider(name)` / `get_llm(name)`
- 支持“默认模型”与按请求切换模型
   示例 DB 表：`models`（id, name, type (embedding|llm), config JSON, status, created_at）

## 2. KnowledgeBaseManager（知识库/向量管理）

职责：

- 管理多个知识库（kb），每个 kb 对应一套文档集合和向量索引
- 提供接口：`create_kb(name)`, `ingest_documents(kb, docs)`, `query_kb(kb, query, k)`
- 支持本地 FAISS 索引持久化：`save_local(kb)`, `load_local(kb)`
- 元数据保存在 MySQL（document 表：id, kb_id, title, source, content, embedding_id,...）
- 支持分片、版本（snapshot）

## 3. ConversationManager（多轮对话）

职责：

- 管理会话对象（session_id, user_id, messages[], metadata）
- 提供 conversation memory（短期与长期）
- 支持将检索到的片段注入 prompt（RAG）
- 支持对话转写为文档入库（长期记忆）

DB 表：`conversations` (id, user_id, title, created_at)，`messages` (id, conversation_id, role, text, metadata, created_at)

## 4. Agent Orchestrator（自定义智能体）

职责：

- 将 LangChain Agent 与工具（retriever、calculator、external API）组合
- 提供 Agent 模板配置：工具集合、策略（单步/多步/chain-of-thought 开/关）
- 记录 `agent_scratchpad` 用于审计与回溯
- 提供 API 启动/停止智能体、获取工具调用日志

## 5. Jobs / Workers

职责：

- 异步嵌入计算（batch embedding）、文档分块、定期 reindex
- 可使用 Celery + Redis（或简单的线程池）实现

------

# 四、MySQL 设计（简化版 schema）

```sql
-- models: 存放模型信息（embedding/llm）
CREATE TABLE models (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(128) NOT NULL,
  type VARCHAR(32) NOT NULL, -- 'embedding' or 'llm'
  config JSON NOT NULL,      -- 存放 endpoint/api_key/其他配置
  is_default BOOLEAN DEFAULT FALSE,
  status VARCHAR(32) DEFAULT 'active',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- knowledge bases
CREATE TABLE knowledge_bases (
  id INT AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(128) UNIQUE,
  description TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- documents
CREATE TABLE documents (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  kb_id INT,
  title VARCHAR(512),
  content LONGTEXT,
  source VARCHAR(512),
  metadata JSON,
  embedding_id VARCHAR(128),  -- 可选 linkage 到向量存储的 id
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (kb_id) REFERENCES knowledge_bases(id)
);

-- conversations + messages
CREATE TABLE conversations (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  user_id INT,
  title VARCHAR(255),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE messages (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  conversation_id BIGINT,
  role VARCHAR(32),   -- user, assistant, system, tool
  content LONGTEXT,
  metadata JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (conversation_id) REFERENCES conversations(id)
);

-- audit log for agent/tool calls
CREATE TABLE tool_calls (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  agent_id VARCHAR(128),
  tool_name VARCHAR(128),
  call_input JSON,
  call_output JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

------

# 五、目录结构（企业级示例）

```
langchain-learning-kit/
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── nginx/
├── app/
│   ├── main.py                    # FastAPI entry
│   ├── config.py
│   ├── api/
│   │   ├── v1/
│   │   │   ├── models.py          # model management endpoints
│   │   │   ├── kb.py              # knowledge base endpoints
│   │   │   ├── conv.py            # conversation endpoints
│   │   │   └── agent.py           # agent endpoints
│   ├── services/
│   │   ├── model_manager.py
│   │   ├── kb_manager.py
│   │   ├── conv_manager.py
│   │   └── agent_orchestrator.py
│   ├── db/
│   │   ├── models.py              # SQLAlchemy models
│   │   ├── session.py
│   │   └── alembic/
│   ├── embeddings/
│   │   ├── openai_provider.py
│   │   └── providers.py
│   └── utils/
│       ├── text_splitter.py
│       ├── faiss_helper.py
│       └── logger.py
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
│   ├── architecture.md
│   └── runbook.md
├── scripts/
│   ├── ingest_docs.py
│   └── reindex_faiss.py
├── .env
├── requirements.txt
└── README.md
```

------

# 六、关键 API 设计

## 1. Model 管理

- `POST /api/v1/models` — 添加模型（body: name,type,config）
- `GET /api/v1/models` — 列表
- `PUT /api/v1/models/{id}` — 更新
- `DELETE /api/v1/models/{id}`

## 2. 知识库

- `POST /api/v1/kb` — 创建知识库
- `POST /api/v1/kb/{kb_id}/ingest` — 上传文档（文本/URL），触发分割+嵌入（异步）
- `POST /api/v1/kb/{kb_id}/query` — query（query, model, k）
- `GET /api/v1/kb/{kb_id}/status` — index 状态

## 3. 会话

- `POST /api/v1/conversations` — 新会话
- `POST /api/v1/conversations/{id}/messages` — 追加消息（会触发 RAG/Agent）
- `GET /api/v1/conversations/{id}` — 获取对话历史

## 4. Agent

- `POST /api/v1/agent/run` — {agent_name, input, model?}
- `GET /api/v1/agent/logs/{run_id}`