代码结构说明 - 元素码农

发布时间: 2025-03-29 18:52

↑

# 代码结构说明

本文将介绍LangChain项目的标准结构和最佳实践，帮助你更好地组织和管理代码。

## 项目结构

一个典型的LangChain项目结构如下：

```
project_root/
├── .env                 # 环境变量配置
├── requirements.txt     # 项目依赖
├── README.md           # 项目说明
├── src/                # 源代码目录
│   ├── chains/         # 自定义Chain
│   ├── prompts/        # 提示模板
│   ├── models/         # 模型配置
│   ├── tools/          # 自定义工具
│   ├── utils/          # 工具函数
│   └── main.py         # 主程序
├── tests/              # 测试代码
└── data/               # 数据文件
    ├── documents/      # 文档数据
    └── vectors/        # 向量存储
```

## 代码组织

### 1. 环境配置

```python
# .env
OPENAI_API_KEY=your-api-key-here
HUGGINGFACEHUB_API_TOKEN=your-token-here
```

```python
# src/config.py
from dotenv import load_dotenv
import os

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
MODEL_NAME = "gpt-3.5-turbo"
TEMPERATURE = 0.7
```

### 2. 提示模板管理

```python
# src/prompts/qa_prompts.py
from langchain.prompts import PromptTemplate

QA_TEMPLATE = """
请回答以下问题：
{question}

要求：
1. 准确简洁
2. 给出示例
3. 说明原理
"""

qa_prompt = PromptTemplate(
    input_variables=["question"],
    template=QA_TEMPLATE
)
```

### 3. Chain定义

```python
# src/chains/qa_chain.py
from langchain.chains import LLMChain
from langchain.llms import OpenAI
from ..prompts.qa_prompts import qa_prompt
from ..config import OPENAI_API_KEY, TEMPERATURE

def create_qa_chain():
    llm = OpenAI(
        temperature=TEMPERATURE,
        openai_api_key=OPENAI_API_KEY
    )
    return LLMChain(llm=llm, prompt=qa_prompt)
```

### 4. 工具函数

```python
# src/utils/text_utils.py
def clean_text(text: str) -> str:
    """清理文本中的特殊字符"""
    return text.strip().replace('\n', ' ')

def split_text(text: str, chunk_size: int = 1000) -> list:
    """将文本分割成小块"""
    return [text[i:i+chunk_size] 
            for i in range(0, len(text), chunk_size)]
```

### 5. 主程序

```python
# src/main.py
from chains.qa_chain import create_qa_chain
from utils.text_utils import clean_text

def main():
    # 创建QA链
    chain = create_qa_chain()
    
    # 处理用户输入
    while True:
        question = input("请输入问题（输入q退出）：")
        if question.lower() == 'q':
            break
            
        # 清理输入
        question = clean_text(question)
        
        # 获取答案
        response = chain.run(question)
        print(f"\n回答：\n{response}\n")

if __name__ == "__main__":
    main()
```

## 最佳实践

### 1. 配置管理
- 使用环境变量存储敏感信息
- 集中管理配置参数
- 区分开发和生产环境

### 2. 代码模块化
- 功能单一原则
- 适当的代码注释
- 清晰的模块划分

### 3. 错误处理

```python
from typing import Optional

def get_response(chain, question: str) -> Optional[str]:
    try:
        return chain.run(question)
    except Exception as e:
        print(f"Error: {e}")
        return None
```

### 4. 日志记录

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    filename='app.log'
)

logger = logging.getLogger(__name__)

def process_request(chain, question: str) -> str:
    logger.info(f"Processing question: {question}")
    response = chain.run(question)
    logger.info(f"Generated response: {response[:100]}...")
    return response
```

### 5. 测试用例

```python
# tests/test_qa_chain.py
import pytest
from src.chains.qa_chain import create_qa_chain

def test_qa_chain():
    chain = create_qa_chain()
    question = "什么是Python？"
    response = chain.run(question)
    
    assert response
    assert len(response) > 0
    assert isinstance(response, str)
```

## 性能优化

### 1. 缓存管理
```python
from functools import lru_cache

@lru_cache(maxsize=100)
def get_cached_response(question: str) -> str:
    chain = create_qa_chain()
    return chain.run(question)
```

### 2. 批处理
```python
from typing import List

def batch_process(questions: List[str], 
                 batch_size: int = 5) -> List[str]:
    chain = create_qa_chain()
    responses = []
    
    for i in range(0, len(questions), batch_size):
        batch = questions[i:i+batch_size]
        responses.extend([chain.run(q) for q in batch])
    
    return responses
```

## 总结

良好的代码结构和最佳实践可以帮助你：
- 提高代码可维护性
- 增强系统可扩展性
- 便于团队协作
- 提升开发效率

遵循这些规范和建议，将帮助你构建更加健壮和可维护的LangChain应用。