langchain-learning-kit/langchain-learning-kit.md

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）

-- 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}