agent_proj/docs/LANGCHAIN_PACKAGE_MAP.md

# LangChain 包地图 (Package Map)

> 本项目使用的 LangChain 相关包一览，按功能模块分类

---

## 1. 核心包 (Core Packages)

### langchain-core
| 类/函数 | 导入路径 | 用途 |
|---------|----------|------|
| `tool` | `langchain_core.tools` | 装饰器方式定义 Agent 工具 |
| `Embeddings` | `langchain_core.embeddings` | Embedding 模型抽象基类 |
| `BaseChatModel` | `langchain_core.chat_models` | 聊天模型抽象基类 |
| `PromptTemplate` | `langchain_core.prompts` | Prompt 模板构建 |
| `StrOutputParser` | `langchain_core.output_parsers` | 输出解析为字符串 |
| `Document` | `langchain_core.documents` | 文档对象 |
| `ToolMessage` | `langchain_core.messages` | 工具返回消息 |
| `AIMessage` | `langchain_core.messages` | AI 消息对象 |

### langchain
| 类/函数 | 导入路径 | 用途 |
|---------|----------|------|
| `create_agent` | `langchain.agents` | 创建 LangChain Agent |
| `AgentState` | `langchain.agents` | Agent 状态定义 |
| `wrap_tool_call` | `langchain.agents.middleware` | 工具调用包装器 |
| `before_model` | `langchain.agents.middleware` | 模型调用前钩子 |
| `dynamic_prompt` | `langchain.agents.middleware` | 动态提示词装饰器 |
| `ModelRequest` | `langchain.agents.middleware` | 模型请求对象 |

---

## 2. 社区包 (Community Packages)

### langchain-community
| 类/函数 | 导入路径 | 用途 |
|---------|----------|------|
| `ChatTongyi` | `langchain_community.chat_models.tongyi` | 通义千问模型 |
| `BaseChatModel` | `langchain_community.chat_models` | 社区版聊天模型基类 |
| `DashScopeEmbeddings` | `langchain_community.embeddings` | 阿里 DashScope Embedding |
| `PyPDFLoader` | `langchain_community.document_loaders` | PDF 文件加载 |
| `TextLoader` | `langchain_community.document_loaders` | TXT 文件加载 |
| `Document` | `langchain_community.docstore.document` | 社区版文档对象 |

---

## 3. 特定集成包 (Integration Packages)

### langchain-chroma
| 类/函数 | 导入路径 | 用途 |
|---------|----------|------|
| `Chroma` | `langchain_chroma` | Chroma 向量数据库 |

### langchain-text-splitters
| 类/函数 | 导入路径 | 用途 |
|---------|----------|------|
| `RecursiveCharacterTextSplitter` | `langchain_text_splitters` | 递归文本分片器 |

---

## 4. LangGraph 相关包

### langgraph
| 类/函数 | 导入路径 | 用途 |
|---------|----------|------|
| `Command` | `langgraph.types` | LangGraph 命令对象 |
| `Runtime` | `langgraph.runtime` | LangGraph 运行时 |
| `ToolCallRequest` | `langchain.tools.tool_node` | 工具调用请求 |

---

## 5. 包依赖关系图

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户代码 (app.py)                         │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      langchain.agents                           │
│                    (create_agent, middleware)                    │
└───────────────┬─────────────────────┬───────────────────────────┘
                │                     │
                ▼                     ▼
┌───────────────────────────┐ ┌───────────────────────────────────┐
│    langchain-core         │ │    langchain-community             │
│  - tools (tool)           │ │  - chat_models.tongyi (ChatTongyi)│
│  - prompts (PromptTemplate)│ │  - embeddings (DashScope)         │
│  - output_parsers         │ │  - document_loaders                │
│  - messages               │ │  - docstore.document                │
└───────────────┬───────────┘ └───────────────┬───────────────────┘
                │                             │
                ▼                             ▼
┌───────────────────────────┐ ┌───────────────────────────────────┐
│   langchain-text-splitters│ │       langchain-chroma             │
│ (RecursiveCharacterText   │ │       (Chroma)                     │
│  Splitter)                │ │                                    │
└───────────────────────────┘ └───────────────────────────────────┘
                                    │
                                    ▼
                             ┌─────────────┐
                             │  Chroma DB  │
                             └─────────────┘
```

---

## 6. 项目中的实际使用示例

### 6.1 工具定义
```python
from langchain_core.tools import tool

@tool(description="查询天气")
def get_weather(city: str) -> str:
    return f"{city}天气晴朗"
```

### 6.2 Agent 创建
```python
from langchain.agents import create_agent
from langchain_community.chat_models.tongyi import ChatTongyi

agent = create_agent(
    model=ChatTongyi(model="qwen3-max"),
    tools=[get_weather],
    system_prompt="你是一个智能助手"
)
```

### 6.3 RAG Chain
```python
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import PromptTemplate

chain = prompt_text | model | StrOutputParser()
```

### 6.4 向量存储
```python
from langchain_chroma import Chroma
from langchain_community.embeddings import DashScopeEmbeddings

vector_store = Chroma(
    collection_name="agent",
    embedding_function=DashScopeEmbeddings(model="text-embedding-v4"),
    persist_directory="chroma_db"
)
```

### 6.5 文档加载
```python
from langchain_community.document_loaders import PyPDFLoader, TextLoader

pdf_docs = PyPDFLoader("file.pdf").load()
txt_docs = TextLoader("file.txt", encoding="utf-8").load()
```

### 6.6 文本分片
```python
from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=200,
    chunk_overlap=20,
    separators=["\n\n", "\n", ".", "!", "?"]
)
```

---

## 7. 包版本要求参考

```
langchain>=0.3.0
langchain-core>=0.3.0
langchain-community>=0.3.0
langchain-chroma>=0.1.0
langchain-text-splitters>=0.3.0
langgraph>=0.2.0
```

---

## 8. QA

### Q1: langchain-core 和 langchain-community 的区别?
- **langchain-core**: LangChain 核心抽象接口，不包含具体实现
- **langchain-community**: 第三方集成 (如通义千问、DashScope)

### Q2: 为什么选择 langchain-chroma 而不是直接用 chromadb?
- LangChain 封装了统一的接口，便于后续更换向量数据库
- 与 LangChain Chain/Agent 更好地集成

### Q3: middleware 机制的实现原理?
- 基于 LangGraph 的钩子系统
- `wrap_tool_call`: 包装工具调用前后逻辑
- `before_model`: 模型调用前的预处理
- `dynamic_prompt`: 动态生成提示词