# rust-ai-framework

**Repository Path**: javpower/rust-ai-framework

## Basic Information

- **Project Name**: rust-ai-framework
- **Description**: A comprehensive Rust framework for AI/ML applications with support for Large Language Models (LLMs), embeddings, RAG (Retrieval-Augmented Generation), reranking, function calling, workflow management, and Model Context Protocol (MCP).
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-08
- **Last Updated**: 2025-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rust AI 框架

一个用 Rust 编写的全功能 AI/ML 应用开发框架，提供了构建现代 AI 应用所需的全部功能，包括大语言模型（LLM）集成、向量嵌入、RAG（检索增强生成）、重排序、函数调用、工作流管理和模型上下文协议（MCP）支持。

## 🌟 主要特性

### 🤖 大语言模型 (LLM) 集成
- **多提供商支持**: OpenAI、Anthropic、本地模型
- **统一接口**: 简化不同 LLM 提供商的使用
- **流式响应**: 支持实时流式输出
- **函数调用**: 完整的工具调用支持
- **错误处理**: 智能重试和错误恢复

### 🔍 向量嵌入 (Embedding)
- **向量生成**: 批量和单个文本向量化
- **相似度搜索**: 高效的语义相似度计算
- **聚类分析**: K-means 聚类算法
- **向量运算**: 余弦相似度、欧几里得距离等

### 📚 检索增强生成 (RAG)
- **文档管理**: 自动文档分块和索引
- **语义搜索**: 基于向量的语义检索
- **结果重排**: 智能结果排序优化
- **上下文管理**: 动态上下文组装

### 🔧 函数调用 (Function Call)
- **工具定义**: 灵活的工具定义系统
- **参数验证**: 自动参数类型检查
- **并行执行**: 支持并行工具调用
- **错误处理**: 完善的错误处理机制

### 🔄 工作流管理 (Flow)
- **流程定义**: 可视化流程定义
- **依赖管理**: 智能依赖解析
- **状态跟踪**: 实时执行状态监控
- **错误恢复**: 自动错误恢复机制

### 🌐 MCP 协议支持
- **MCP 服务器**: 完整的 MCP 服务器实现
- **MCP 客户端**: 灵活的客户端连接
- **MCP 代理**: 负载均衡和路由
- **WebSocket**: 实时双向通信

## 🏗️ 项目结构

```
rust-ai/
├── src/
│   ├── core.rs              # 核心类型和特征
│   ├── error.rs             # 错误定义
│   ├── config.rs            # 配置管理
│   ├── utils.rs             # 工具函数
│   ├── lib.rs               # 库入口点
│   ├── llm/                 # 大语言模型提供商
│   │   ├── mod.rs
│   │   ├── openai.rs        # OpenAI 集成
│   │   ├── anthropic.rs     # Anthropic 集成
│   │   └── local.rs         # 本地模型支持
│   ├── embedding/           # 嵌入提供商
│   │   ├── mod.rs
│   │   ├── openai.rs        # OpenAI 嵌入
│   │   └── local.rs         # 本地嵌入模型
│   ├── rag/                 # RAG 系统
│   │   └── mod.rs
│   ├── reranking/           # 结果重排序
│   │   └── mod.rs
│   ├── function_call/       # 函数调用框架
│   │   └── mod.rs
│   ├── flow/                # 工作流管理
│   │   └── mod.rs
│   ├── mcp/                 # 模型上下文协议
│   │   ├── mod.rs
│   │   ├── protocol.rs      # MCP 协议定义
│   │   ├── server.rs        # MCP 服务器实现
│   │   ├── client.rs        # MCP 客户端实现
│   │   └── proxy.rs         # MCP 代理实现
│   └── bin/                 # 二进制可执行文件
│       ├── mcp_server.rs    # MCP 服务器二进制
│       ├── mcp_client.rs    # MCP 客户端二进制
│       └── mcp_proxy.rs     # MCP 代理二进制
├── Cargo.toml               # 项目依赖
├── example_config.json      # 示例配置
└── README_ch.md            # 本文档
```

## 🚀 快速开始

### 安装依赖

1. 克隆项目：
```bash
git clone <repository-url>
cd rust-ai
```

2. 构建项目：
```bash
cargo build
```

3. 运行测试：
```bash
cargo test
```

### 配置设置

创建配置文件（例如 `config.json`），添加你的 API 密钥和设置：

```json
{
  "llm": {
    "openai": {
      "api_key": "your-openai-api-key",
      "base_url": "https://api.openai.com/v1",
      "model": "gpt-4"
    },
    "anthropic": {
      "api_key": "your-anthropic-api-key",
      "model": "claude-3-sonnet-20240229"
    }
  },
  "embedding": {
    "openai": {
      "api_key": "your-openai-api-key",
      "model": "text-embedding-3-small"
    }
  },
  "mcp": {
    "server": {
      "host": "127.0.0.1",
      "port": 8080
    }
  }
}
```

## 📝 使用示例

### 基本 LLM 使用

```rust
use rust_ai_framework::{LlmProvider, LlmRequest, LlmResponse};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 使用配置初始化
    let config = rust_ai_framework::config::Config::from_file("config.json")?;
    rust_ai_framework::init_with_config(&config)?;
    
    // 创建 LLM 提供商
    let provider = rust_ai_framework::llm::OpenAiProvider::new(config.llm.openai);
    
    // 生成文本
    let request = LlmRequest {
        prompt: "你好，你好吗？".to_string(),
        max_tokens: 100,
        temperature: 0.7,
        ..Default::default()
    };
    
    let response = provider.generate(request).await?;
    println!("响应: {}", response.text);
    
    Ok(())
}
```

### RAG 系统使用

```rust
use rust_ai_framework::{rag::RagSystem, Document};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rag = RagSystem::new();
    
    // 添加文档
    let document = Document {
        id: uuid::Uuid::new_v4(),
        content: "这是一个关于 AI 的示例文档。".to_string(),
        metadata: Default::default(),
    };
    
    rag.add_document(document).await?;
    
    // 搜索文档
    let results = rag.search("AI", 5).await?;
    for result in results {
        println!("找到: {}", result.document.content);
    }
    
    Ok(())
}
```

### MCP 服务器使用

运行 MCP 服务器：

```bash
cargo run --bin mcp-server -- --host 127.0.0.1 --port 8080
```

运行 MCP 客户端：

```bash
cargo run --bin mcp-client -- --server 127.0.0.1:8080
```

运行 MCP 代理：

```bash
cargo run --bin mcp-proxy -- --upstream 127.0.0.1:8080 --port 8081
```

## 🔧 API 参考

### 核心类型

- `LlmRequest`: LLM 生成请求结构
- `LlmResponse`: LLM 生成响应结构
- `Document`: RAG 系统文档结构
- `SearchResult`: 搜索结果结构
- `FunctionCall`: 函数调用定义
- `WorkflowStep`: 工作流步骤定义

### 特征 (Traits)

- `LlmProvider`: LLM 提供商特征
- `EmbeddingProvider`: 嵌入提供商特征
- `RagProvider`: RAG 系统提供商特征
- `RerankingProvider`: 重排序提供商特征
- `FunctionCallProvider`: 函数调用提供商特征
- `WorkflowProvider`: 工作流管理提供商特征

## 🛠️ 错误处理

框架提供全面的错误处理，包含特定的错误类型：

- `Error::Config`: 配置相关错误
- `Error::Llm`: LLM 相关错误
- `Error::Embedding`: 嵌入相关错误
- `Error::Rag`: RAG 系统错误
- `Error::Mcp`: MCP 协议错误
- `Error::Io`: I/O 错误

## 🌟 特性说明

### 多提供商支持
框架支持多种 AI 服务提供商，可以轻松切换或同时使用多个提供商。

### 类型安全
利用 Rust 的类型系统，在编译时捕获错误，提高代码质量。

### 异步支持
全面的异步支持，提供高性能的并发处理能力。

### 错误处理
完善的错误处理机制，包括自动重试和错误恢复。

### 可扩展性
模块化设计，易于扩展新的提供商和功能。

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📄 许可证

本项目使用 MIT 许可证 - 详情请参阅 LICENSE 文件。

## 📦 依赖项

- `tokio`: 异步运行时
- `serde`: 序列化/反序列化
- `serde_json`: JSON 处理
- `uuid`: UUID 生成
- `chrono`: 日期/时间处理
- `anyhow`: 错误处理
- `thiserror`: 错误类型定义

## 🗺️ 开发路线图

- [ ] 添加更多 LLM 提供商支持（Cohere、Hugging Face 等）
- [ ] 实现向量数据库集成（Pinecone、Weaviate 等）
- [ ] 添加 LLM 响应流式支持
- [ ] 实现缓存层
- [ ] 添加监控和指标
- [ ] 创建配置和管理的 Web UI
- [ ] 添加微调工作流支持
- [ ] 实现自定义提供商插件系统

## 📞 联系我们

如有问题或建议，请通过以下方式联系：

- 创建 GitHub Issue
- 发送邮件至 [javpower.class@gmail.com]

## 🙏 致谢

感谢所有贡献者和开源社区的支持！

---

**Rust AI Framework** - 用 Rust 构建下一代 AI 应用 🚀