# x-dify

**Repository Path**: chain-engine/x-dify

## Basic Information

- **Project Name**: x-dify
- **Description**: 一个完整的 Dify（开源 LLM 应用开发平台）学习和实训项目
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# x-dify

<div align="center">

![x-dify](https://img.shields.io/badge/x--dify-0.1.0-blue)
![Python](https://img.shields.io/badge/Python-3.11+-green)
![FastAPI](https://img.shields.io/badge/FastAPI-Latest-red)
![License](https://img.shields.io/badge/License-MIT-yellow)

**生产级 LLM 应用开发平台**

Dify 学习实训项目 - 遵循行业最佳工程实践

[快速开始](#快速开始) · [文档](https://gitee.com/yeyushilai/x-dify) · [示例](#示例) · [贡献](#贡献)

</div>

## 项目简介

x-dify 是一个完整的 Dify（开源 LLM 应用开发平台）学习和实训项目，遵循行业最佳工程实践，提供标准化、模块化、高可扩展、高可维护的基础架构。核心编码逻辑体现 Dify 的全流程和主流技术栈。

## 核心特征

- **分层架构**：清晰的 API、Service、Repository 三层架构
- **依赖注入**：内置类 Go Wire 风格的依赖注入容器
- **标准化响应**：统一的 API 响应格式和错误处理
- **完整日志**：基于 loguru 的结构化日志系统
- **双配置体系**：支持 .env 环境变量 + YAML 配置文件
- **中间件支持**：CORS、限流、请求追踪等中间件
- **异步支持**：基于 FastAPI 的全异步架构
- **生产级代码**：完整的类型注解、文档字符串、单元测试

## 项目结构

```
x-dify/
├── config/                 # 配置文件目录
│   ├── config.yaml         # 主配置文件
│   └── .env.example        # 环境变量示例
├── docs/                   # 项目文档
├── examples/               # 使用示例
│   ├── llm_chat.py         # LLM聊天示例
│   ├── document_upload.py  # 文档上传示例
│   ├── config_example.py   # 配置管理示例
│   └── dependency_injection.py  # 依赖注入示例
├── scripts/                # 部署脚本
│   ├── start.sh            # Linux启动脚本
│   ├── start.ps1           # Windows启动脚本
│   ├── test.sh             # Linux测试脚本
│   ├── test.ps1            # Windows测试脚本
│   ├── lint.sh             # Linux代码检查脚本
│   └── lint.ps1            # Windows代码检查脚本
├── src/                    # 核心业务代码
│   ├── api/                # API层
│   │   ├── v1/             # API v1版本
│   │   │   ├── health.py   # 健康检查
│   │   │   ├── version.py  # 版本信息
│   │   │   ├── llm.py      # LLM接口
│   │   │   └── document.py # 文档接口
│   │   └── router.py       # 路由管理
│   ├── common/             # 公共模块
│   │   ├── constants.py    # 全局常量
│   │   ├── response.py     # 响应标准化
│   │   └── schemas.py      # 数据模型
│   ├── core/               # 核心模块
│   │   ├── config.py       # 配置管理
│   │   ├── logger.py       # 日志管理
│   │   ├── exceptions.py   # 异常定义
│   │   ├── container.py    # 依赖注入容器
│   │   └── middleware.py   # 中间件
│   ├── models/             # 数据模型
│   │   ├── base.py         # 基类
│   │   ├── document.py     # 文档模型
│   │   └── llm.py          # LLM模型
│   ├── repositories/       # 数据访问层
│   │   └── document_repository.py
│   ├── services/           # 业务逻辑层
│   │   ├── llm_service.py  # LLM服务
│   │   └── document_service.py
│   ├── utils/              # 工具函数
│   │   ├── helpers.py      # 辅助函数
│   │   └── validators.py   # 验证器
│   └── main.py             # 应用入口
├── tests/                  # 测试用例
│   ├── conftest.py         # 测试配置
│   ├── test_config.py      # 配置测试
│   ├── test_utils.py       # 工具测试
│   └── test_api.py         # API测试
├── .gitignore              # Git忽略文件
├── .python-version         # Python版本
├── Dockerfile              # Docker配置
├── docker-compose.yml      # Docker Compose配置
├── LICENSE                 # MIT许可证
├── pyproject.toml          # 项目配置
└── README.md               # 项目说明
```

## 系统架构

### 分层架构

```mermaid
graph TD
    A[API Layer] --> B[Service Layer]
    B --> C[Repository Layer]
    B --> D[External Services]
    C --> E[Database/Cache]
    F[Core Components] --> A
    F --> B
    F --> C
    G[Common Modules] --> A
    G --> B
    G --> C
```

### LLM对话流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant API as API层
    participant Service as 服务层
    participant Provider as LLM提供商
    participant DB as 数据库

    Client->>API: 发送聊天请求
    API->>Service: 调用聊天服务
    Service->>Provider: 调用LLM API
    Provider-->>Service: 返回响应
    Service->>DB: 保存对话记录
    Service-->>API: 返回结果
    API-->>Client: 返回响应
```

## 快速开始

### 环境要求

- Python 3.11 或更高版本
- uv 包管理器

#### Windows

1. 安装 Python 3.11+
   ```powershell
   # 从 python.org 下载安装或使用 winget
   winget install Python.Python.3.11
   ```

2. 验证 Python 版本
   ```powershell
   python --version
   ```

#### Linux/macOS

1. 安装 Python 3.11+
   ```bash
   # Ubuntu/Debian
   sudo apt update
   sudo apt install python3.11 python3.11-venv

   # macOS
   brew install python@3.11
   ```

2. 验证 Python 版本
   ```bash
   python3.11 --version
   ```

### 项目克隆

```bash
git clone https://gitee.com/yeyushilai/x-dify.git
cd x-dify
```

### 依赖安装

```bash
# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 Python 安装
python -m pip install uv

# 安装项目依赖
uv pip install -e .
```

### 配置文件创建

1. 复制环境变量示例文件
   ```bash
   cp config/.env.example config/.env
   ```

2. 编辑 `.env` 文件，配置必要的环境变量
   ```bash
   # LLM配置
   DEEPSEEK_API_KEY=your_api_key_here
   ```

3. 如需自定义配置，编辑 `config/config.yaml`

### 服务启动

#### 本地开发模式（支持热重载、调试）

##### Windows

```powershell
# 使用脚本启动
.\scripts\start.ps1 --reload

# 或直接使用uvicorn
python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

##### Linux/macOS

```bash
# 使用脚本启动
./scripts/start.sh --reload

# 或直接使用uvicorn
python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
```

#### Docker 容器化部署

```bash
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f x-dify
```

### 常用命令

```bash
# 运行测试
pytest tests/ -v

# 运行测试并生成覆盖率报告
pytest tests/ --cov=src --cov-report=html

# 代码格式化
black src/ tests/ examples/

# 代码检查
ruff check src/ tests/ examples/

# 类型检查
mypy src/
```

## 技术栈

### Web 框架
- **FastAPI**: 现代、高性能的 Web 框架
- **Uvicorn**: ASGI 服务器
- **Pydantic**: 数据验证和序列化

### 数据存储
- **SQLite**: 轻量级数据库（默认）
- **PostgreSQL**: 生产环境数据库（可选）
- **Redis**: 缓存服务（可选）

### 工具库
- **loguru**: 日志管理
- **PyYAML**: YAML 配置解析
- **python-dotenv**: 环境变量管理
- **httpx**: 异步 HTTP 客户端
- **slowapi**: 限流中间件

### 部署工具
- **Docker**: 容器化部署
- **Docker Compose**: 多容器编排

## API 文档

服务启动后，可以通过以下地址访问 API 文档：

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json

### 主要接口

#### 健康检查
```bash
GET /api/v1/health
```

#### 版本信息
```bash
GET /api/v1/version
```

#### LLM 聊天
```bash
POST /api/v1/llm/chat
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "temperature": 0.7,
  "max_tokens": 200
}
```

#### 文档上传
```bash
POST /api/v1/documents/upload
Content-Type: multipart/form-data

file: example.txt
chunk_size: 500
chunk_overlap: 50
```

## 存储配置

### 本地存储

- **日志文件**: `logs/app.log`
- **数据文件**: `data/`
- **向量存储**: `data/vector_store/`

### 对象存储（计划中）

未来将支持 S3、OSS 等对象存储服务。

## 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

## 参考资料

- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
- [Python 官方文档](https://docs.python.org/3.11/)
- [Pydantic 文档](https://docs.pydantic.dev/)
- [Uvicorn 文档](https://www.uvicorn.org/)
- [uv 文档](https://github.com/astral-sh/uv)

## 联系方式

- **作者**: 夜雨诗来
- **邮箱**: john.young@foxmail.com
- **Gitee**: https://gitee.com/yeyushilai
- **GitHub**: https://github.com/yeyushilai

## 贡献

欢迎提交 Issue 和 Pull Request！