# x-llm-app

**Repository Path**: chain-engine/x-llm-app

## Basic Information

- **Project Name**: x-llm-app
- **Description**: 一个面向生产环境的大语言模型应用开发框架
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-LLM-App

> 企业级大语言模型（LLM）应用开发框架

X-LLM-App 是一个面向生产环境的 LLM 应用开发框架，提供了一套完整的抽象层和基础设施，帮助开发者快速构建安全、可靠、可扩展的 LLM 原生应用。

---

## 📌 目录

- [核心特性](#-核心特性)
- [快速开始](#-快速开始)
- [框架架构](#-框架架构)
- [核心概念](#-核心概念)
- [使用指南](#-使用指南)
- [示例代码](#-示例代码)
- [项目结构](#-项目结构)
- [配置说明](#-配置说明)
- [测试与质量保障](#-测试与质量保障)
- [许可证](#-许可证)
- [支持与贡献](#-支持与贡献)

---

## ✨ 核心特性

### 框架级能力

- **模块化架构**：清晰的抽象层设计，支持灵活扩展
- **插件系统**：通过工具和中间件机制实现功能扩展
- **生命周期管理**：完整的应用生命周期管理（初始化、运行、关闭）
- **上下文管理**：统一的上下文传递机制，支持会话管理

### LLM 集成

- **多模型支持**：支持 DeepSeek、豆包、阿里云通义千问等主流 LLM 后端
- **统一接口**：提供统一的模型调用接口，屏蔽底层差异
- **流式传输**：支持多种流式传输模式（updates、messages、custom）
- **对话记忆**：内置对话历史管理，支持连续对话

### 开发体验

- **声明式工具**：通过装饰器快速定义工具
- **中间件机制**：灵活的请求/响应处理管道
- **类型安全**：完整的类型注解，提供良好的 IDE 支持
- **配置管理**：统一的配置管理，支持环境变量

### 生产就绪

- **安全合规**：API 密钥管理、输入/输出过滤
- **可观测性**：结构化日志、错误追踪
- **错误处理**：统一的错误处理机制
- **性能优化**：支持异步调用、批量处理

---

## 🚀 快速开始

### 环境要求

- Python 3.10 或更高版本
- 推荐使用 [`uv`](https://github.com/astral-sh/uv) 作为包管理器

### 安装

```bash
# 克隆项目
git clone https://github.com/yeyushilai-team/x-llm-app.git
cd x-llm-app

# 安装依赖
uv sync

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入必要的 API 密钥
```

### 第一个应用

```python
from core import XLLMApp, AgentFactory, AgentConfig

# 创建应用
app = XLLMApp(name="my-first-app")

# 创建 Agent
config = AgentConfig(
    model_name="deepseek",
    system_prompt="你是一个友好的助手"
)
agent = AgentFactory.create(config)

# 调用 Agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "你好"}]
})

print(result)
```

### 运行示例

```bash
# 查看所有示例
ls examples/

# 运行基础示例
uv run python examples/basic_agent.py

# 运行工具示例
uv run python examples/agent_with_tools.py

# 运行中间件示例
uv run python examples/agent_with_middleware.py
```

---

## 🏗️ 框架架构

```
┌─────────────────────────────────────────────────────────┐
│                    XLLMApp                          │
│              (应用生命周期管理)                        │
└─────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
┌───────▼──────┐  ┌────▼──────┐  ┌────▼──────┐
│   Agent      │  │   Model    │  │   Tool     │
│  (智能体)     │  │  (模型)     │  │  (工具)     │
└──────────────┘  └───────────┘  └───────────┘
        │                 │                 │
        └─────────────────┼─────────────────┘
                          │
                   ┌──────▼──────┐
                   │ Middleware  │
                   │  (中间件)    │
                   └─────────────┘
                          │
                   ┌──────▼──────┐
                   │  Context    │
                   │  (上下文)    │
                   └─────────────┘
```

---

## 📚 核心概念

### 1. 应用（XLLMApp）

应用是框架的入口点，负责管理整个应用的生命周期。

```python
from core import XLLMApp

app = XLLMApp(name="my-app")
app.run()
app.shutdown()
```

### 2. Agent（智能体）

Agent 是应用的核心组件，负责处理用户请求并生成响应。

```python
from core import AgentFactory, AgentConfig

config = AgentConfig(
    model_name="deepseek",
    system_prompt="你是一个智能助手"
)
agent = AgentFactory.create(config)

result = agent.invoke({
    "messages": [{"role": "user", "content": "你好"}]
})
```

### 3. 工具（Tool）

工具是 Agent 可以调用的外部功能，用于扩展 Agent 的能力。

```python
from core.tool import tool

@tool(name="get_weather", description="获取天气信息")
def get_weather(city: str) -> str:
    """获取指定城市的天气。"""
    return f"{city}的天气晴朗"
```

### 4. 中间件（Middleware）

中间件用于在请求和响应处理过程中插入自定义逻辑。

```python
from core.middleware import BaseMiddleware

class LoggingMiddleware(BaseMiddleware):
    def before_request(self, request):
        print(f"Request: {request}")
        return request
    
    def after_request(self, response):
        print(f"Response: {response}")
        return response

app.add_middleware(LoggingMiddleware())
```

### 5. 上下文（Context）

上下文用于存储应用运行时的信息，如用户 ID、会话 ID 等。

```python
from core import Context

context = Context(
    user_id="user123",
    thread_id="session456"
)

result = agent.invoke(input_data, context=context)
```

---

## 📖 使用指南

详细的框架使用指南请参考：[框架使用指南](docs/FRAMEWORK_GUIDE.md)

### 快速链接

- [基础示例](examples/basic_agent.py)
- [工具示例](examples/agent_with_tools.py)
- [中间件示例](examples/agent_with_middleware.py)
- [流式传输示例](examples/streaming_agent.py)
- [对话记忆示例](examples/memory_agent.py)

---

## 💡 示例代码

### 基础 Agent

```python
from core import AgentFactory, AgentConfig

config = AgentConfig(
    model_name="deepseek",
    system_prompt="你是一个友好的助手"
)
agent = AgentFactory.create(config)

result = agent.invoke({
    "messages": [{"role": "user", "content": "你好"}]
})
```

### 使用工具

```python
from core.tool import tool

@tool(name="get_weather", description="获取天气信息")
def get_weather(city: str) -> str:
    """获取指定城市的天气。"""
    return f"{city}的天气晴朗"

config = AgentConfig(
    model_name="deepseek",
    tools=["get_weather"]
)
agent = AgentFactory.create(config)

result = agent.invoke({
    "messages": [{"role": "user", "content": "北京的天气怎么样？"}]
})
```

### 流式传输

```python
config = AgentConfig(
    model_name="deepseek",
    enable_streaming=True,
    streaming_mode="updates"
)
agent = AgentFactory.create(config)

for chunk in agent.stream({
    "messages": [{"role": "user", "content": "介绍一下自己"}]
}):
    print(chunk)
```

更多示例请查看 [examples](examples/) 目录。

---

## 📁 项目结构

```
x-llm-app/
├── core/               # 框架核心模块
│   ├── __init__.py
│   ├── app.py         # 应用主类
│   ├── agent.py       # Agent 抽象
│   ├── tool.py        # 工具抽象
│   ├── model.py       # 模型抽象
│   ├── middleware.py  # 中间件抽象
│   ├── context.py     # 上下文管理
│   └── langchain_agent.py  # LangChain 实现
├── config/            # 配置管理
│   └── settings.py
├── constants/         # 常量定义
│   ├── streaming_modes.py
│   └── develop.py
├── examples/          # 示例代码
│   ├── basic_agent.py
│   ├── agent_with_tools.py
│   └── ...
├── tests/             # 测试代码
├── docs/              # 文档
│   └── FRAMEWORK_GUIDE.md
├── main.py            # 命令行工具
├── pyproject.toml     # 项目配置
└── README.md          # 项目文档
```

---

## ⚙️ 配置说明

### 环境变量配置

项目使用 `.env` 文件存储配置信息：

```env
# DeepSeek 配置
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_API_BASE=https://api.deepseek.com/v1
DEEPSEEK_MODEL_NAME=deepseek-chat

# 豆包配置
DOUBAO_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DOUBAO_API_BASE=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_MODEL_NAME=ep-xxxxxxxxxxxxxx

# 阿里云百炼配置
ALIYUN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ALIYUN_MODEL_NAME=qwen-plus

# 通用配置
TEMPERATURE=0.0
DEBUG=True
```

---

## 🧪 测试与质量保障

### 运行测试

```bash
# 运行所有测试
uv run python -m unittest discover

# 运行特定测试
uv run python -m unittest tests.test_core
```

### 代码质量

- **类型检查**：完整的类型注解
- **单元测试**：核心模块的单元测试
- **集成测试**：端到端集成测试
- **代码规范**：遵循 PEP 8 规范

---

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

---

## 🤝 支持与贡献

### 支持

- 查看 [框架使用指南](docs/FRAMEWORK_GUIDE.md)
- 查看 [示例代码](examples/)
- 提交 [GitHub Issue](https://github.com/yeyushilai-team/x-llm-app/issues)

### 贡献

我们欢迎社区贡献：

- 修复 bug
- 添加新功能
- 改进文档
- 优化性能

请通过 GitHub Pull Request 提交您的贡献。

---

## 📚 参考文档

- [框架使用指南](docs/FRAMEWORK_GUIDE.md)
- [LangChain 文档](https://python.langchain.com/)
- [DeepSeek 文档](https://platform.deepseek.com/docs/api)
- [豆包文档](https://www.doubao.com/)
- [阿里云通义千问文档](https://help.aliyun.com/product/1081203.html)

---

## 🌟 特性路线图

- [ ] 支持更多 LLM 模型
- [ ] 异步调用支持
- [ ] 向量数据库集成
- [ ] RAG（检索增强生成）支持
- [ ] 多模态支持
- [ ] Web UI 界面
- [ ] 分布式部署支持