119 lines
3.8 KiB
Markdown
119 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## 项目概述
|
|
|
|
这是一个基于 LangChain 的学习演示项目,展示如何使用大语言模型进行各种应用场景的开发,包括基础调用、提示词模板、输出解析、向量存储、RAG 检索增强和 Agent。
|
|
|
|
## 环境配置
|
|
|
|
### 依赖管理
|
|
- Python 项目,依赖列表在 `requirements.txt`
|
|
- 安装依赖: `pip install -r requirements.txt`
|
|
- 关键依赖包括: langchain, langchain-openai, langchain-community, python-dotenv, faiss-cpu
|
|
|
|
### 环境变量配置
|
|
项目根目录的 `.env` 文件包含 API 配置:
|
|
- `OPENAI_BASE_URL`: OpenAI API 基础 URL
|
|
- `OPENAI_API_KEY1`: OpenAI API 密钥
|
|
- `LANGSMITH_TRACING`: LangSmith 追踪开关(必须设置为 "true")
|
|
- `LANGSMITH_API_KEY`: LangSmith API 密钥
|
|
- `LANGSMITH_PROJECT`: LangSmith 项目名称
|
|
|
|
注意: 代码中使用 `OPENAI_API_KEY1` 而不是标准的 `OPENAI_API_KEY`
|
|
|
|
## 代码结构
|
|
|
|
### 目录组织
|
|
- `/app/demo/`: 包含演示代码的 Jupyter notebook
|
|
- `demo1.ipynb`: 主要演示文件,包含 7 个核心示例
|
|
- `/models/`: 模型相关文件(目前为空)
|
|
- `/data/`: 数据文件(目前为空)
|
|
- `sample.ipynb`: 根目录的示例 notebook,展示环境配置和基础模型调用
|
|
|
|
### 核心功能模块
|
|
|
|
#### 1. 基础 LLM 调用
|
|
使用 `ChatOpenAI` 调用大模型:
|
|
```python
|
|
from langchain_openai import ChatOpenAI
|
|
llm = ChatOpenAI(model="gpt-4.1-nano")
|
|
response = llm.invoke("你的问题")
|
|
```
|
|
|
|
#### 2. 提示词模板系统
|
|
使用 `ChatPromptTemplate` 创建结构化提示:
|
|
```python
|
|
from langchain_core.prompts import ChatPromptTemplate
|
|
prompt = ChatPromptTemplate.from_messages([
|
|
("system", "系统角色描述"),
|
|
("user", "{input}")
|
|
])
|
|
chain = prompt | llm
|
|
```
|
|
|
|
#### 3. 输出解析
|
|
使用 `JsonOutputParser` 将 LLM 输出解析为 JSON:
|
|
- 使用 `output_parser.get_format_instructions()` 获取格式要求
|
|
- 将格式要求注入到提示词模板中
|
|
|
|
#### 4. 向量存储与检索
|
|
使用 FAISS 向量数据库:
|
|
- 通过 `WebBaseLoader` 抓取网页内容
|
|
- 使用 `RecursiveCharacterTextSplitter` 分割文档(chunk_size=500, chunk_overlap=50)
|
|
- 使用 `OpenAIEmbeddings` (model="text-embedding-3-small") 生成向量
|
|
- 使用 `FAISS.from_documents()` 创建向量存储
|
|
|
|
#### 5. RAG (检索增强生成)
|
|
核心流程:
|
|
1. 使用 `vector.as_retriever()` 创建检索器(k=3)
|
|
2. 检索相关文档片段
|
|
3. 将检索结果作为上下文注入提示词
|
|
4. LLM 基于上下文生成回答
|
|
|
|
#### 6. Agent 系统
|
|
使用 LangChain Agent 实现工具调用:
|
|
- 使用 `create_retriever_tool()` 创建检索工具
|
|
- 使用 `create_openai_functions_agent()` 创建 Agent
|
|
- 使用 `AgentExecutor` 执行 Agent(verbose=True 可查看执行过程)
|
|
|
|
## 开发工作流
|
|
|
|
### 运行 Jupyter Notebooks
|
|
主要开发工作在 Jupyter notebook 中进行:
|
|
- 启动 Jupyter: `jupyter notebook` 或 `jupyter lab`
|
|
- 主要演示代码位于 `app/demo/demo1.ipynb`
|
|
|
|
### 环境初始化模式
|
|
代码使用严格的环境变量检查:
|
|
```python
|
|
import dotenv
|
|
dotenv.load_dotenv()
|
|
# 必须在 .env 中配置所有必需变量,否则会抛出异常
|
|
```
|
|
|
|
### 模型配置
|
|
当前项目使用的模型:
|
|
- LLM: `gpt-4.1-nano` (通过 OpenAI 兼容接口)
|
|
- Embeddings: `text-embedding-3-small`
|
|
|
|
## 技术要点
|
|
|
|
### 链式调用 (Chain)
|
|
使用管道操作符 `|` 组合组件:
|
|
```python
|
|
chain = prompt | llm | output_parser
|
|
result = chain.invoke({"input": "问题"})
|
|
```
|
|
|
|
### 向量检索配置
|
|
- 默认检索 top-k=3 个最相关文档
|
|
- 文档分割使用重叠策略避免语义断裂
|
|
- 向量数据当前存储在内存中,未做持久化
|
|
|
|
### Web 数据加载
|
|
使用 `WebBaseLoader` 抓取特定网页内容:
|
|
- 支持使用 `bs4.SoupStrainer` 精确定位内容区域
|
|
- 示例中抓取中国政府网站的法律条文内容
|