CarrotAI

CarrotAI

🚀 立即在线体验 | SaaS 客户端下载

🇨🇳 阅读中文文档

---

🥕 介绍

CarrotAI 是一款前沿的 AI Agent 应用，通过服务器发送事件（SSE）和可流式传输的 HTTP 提供实时流式聊天，并内置了模型控制协议（MCP）集成。它支持与多个 SSE MCP 服务并发连接，并提供英语、中文和日语用户界面。

🚀 功能特性

• AI Agent：由 SSE 和 MCP 适配器驱动的实时聊天，提供无缝的对话体验。
• 多服务器支持：同时连接并调用多个 SSE MCP 服务，聚合智能响应。
• 多语言：完整的英文、中文和日语本地化支持。
• 深度思考模式：用于复杂或多步骤查询的高级分析。
• 身份验证：使用 JWT 令牌的安全登录/注册流程。
• 响应式 UI：适配移动设备、桌面和网页平台的自适应设计。
• 主题定制：浅色/深色模式、自定义种子颜色，以及通过 dynamic_color 实现的动态 Material 3 主题。
• 文件上传：在对话中附加和解析文件，获得更丰富的上下文。

🤖 支持的大模型 API

• DeepSeek：具有强大推理能力的先进语言大模型

🛠️ 技术栈

前端

• 框架：Flutter
• 状态管理：Provider
• UI：Material Design 3
• 本地化：flutter gen-l10n
• 主题：dynamic_color

后端

• 框架：FastAPI
• 流式传输：服务器发送事件（SSE）
• AI 集成：DeepSeek 大模型、MCP（模型控制协议）
• 数据库：PostgreSQL + SQLAlchemy
• 身份验证：JSON Web 令牌
• 迁移：Alembic
• 部署：Uvicorn & Gunicorn

📋 前置要求

• Flutter SDK ^3.7.2
• Python >=3.12
• PostgreSQL

⚡ 快速开始

请确保已安装 uv

# Clone repository
git clone https://github.com/Xingsandesu/CarrotAI.git && cd CarrotAI

# Deal with environment variables
mv backend/.env.example backend/.env && mv .env.example .env

# Edit environment variables
vim .env
vim backend/.env

# Temporarily start PostgreSQL
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d postgres

# Backend setup
uv run backend/scripts/startup.py --user --email <email> --username <name> --password <password>

# Stop PostgreSQL
docker-compose -f docker-compose.yml -f docker-compose.override.yml down

# Deal with Config
vim config/

# Run Backend
docker compose up -d

🔧 安装

后端设置

1. 导航至后端目录：

   cd backend
   

2. 创建并激活虚拟环境：

   uv sync
   

3. 复制示例环境文件：

   cp .env.example .env
   

4. 应用数据库迁移：

   uv run scripts/init_db.py && uv run scripts/init_config.py
   

5. 运行服务器：

   python main.py       # Development mode
   python main.py prod  # Production mode with Gunicorn
   

前端设置

1. 返回项目根目录：

   cd ..
   

2. 获取 Flutter 依赖：

   flutter pub get
   

3. 生成本地化文件：

   flutter gen-l10n
   

4. 启动应用：

   flutter run
   

5. 构建网页版本：

   flutter build web --wasm
   

🌐 配置

• 前端：编辑 lib/core/config/app_config.dart 以配置 API 端点和主题默认值。
• 后端：配置 .env 和 backend/app/core/config.py 以设置数据库和 MCP 服务。

后端配置文件

后端使用位于 backend/config/ 中的 JSON 文件来定义模型、MCP 服务和自定义适配器。以下是默认文件夹结构：

backend/config/
├── model_configs.json       # LLM model definitions and metadata
├── mcp_servers.json         # SSE MCP server endpoints and env settings
└── app/                     # Custom adapter definitions
    └── duckduckgo-search.json

model_configs.json

定义 CarrotAI 可用的大模型。每个条目包含：

• id（字符串）：唯一的模型标识符。
• icon（字符串）：用于显示的图标名称。
• translations（对象）：本地化的名称和描述（zh、en、ja）。
• exclusiveRules（对象）：功能的切换和排除规则。

示例：

[
  {
    "id": "deepseek",
    "icon": "smart_toy_outlined",
    "translations": {
      "zh": { "name": "DeepSeek", "description": "专注于深度思考和复杂推理的满血模型" },
      "en": { "name": "DeepSeek", "description": "Powerful Chinese large model focused on deep thinking and complex reasoning" },
      "ja": { "name": "DeepSeek", "description": "深い思考と複雑な推論に特化した強力な中国語大規模モデル" }
    },
    "exclusiveRules": {
      "deepThinking": { "enabled": true, "excludes": ["mcpServices"] },
      "mcpServices": { "enabled": true, "excludes": ["deepThinking"] }
    }
  }
]

mcp_servers.json

指定 SSE 模型控制协议（MCP）端点。格式：

• 键：服务名称。
• url（字符串）：SSE 端点 URL。
• env（对象）：适配器的环境变量。

示例：

{
  "serviceA": {
    "url": "http://localhost:10000/sse",
    "env": {
      "API_KEY": "your_api_key"
    }
  }
}

自定义适配器（app/*.json）

在 backend/config/app/ 中放置自定义 MCP 适配器。每个文件定义：

• id（字符串）：适配器标识符。
• icon（字符串）：表情符号或图标名称。
• mcpServer（对象）：与 mcp_servers.json 中的条目具有相同的结构。
• translations（对象）：本地化 UI 元数据。

示例（duckduckgo-search.json）：

{
  "id": "duckduckgo-search",
  "icon": "🔍",
  "mcpServer": {
    "url": "http://localhost:10000/duckduckgo-search",
    "env": {}
  },
  "transportType": "sse",
  "translations": {
    "en": { "name": "DuckDuckGo Search", "type": "Search Tool", "description": "Use DuckDuckGo search engine for secure and private web searches" },
    "zh": { "name": "DuckDuckGo搜索", "type": "搜索工具", "description": "使用DuckDuckGo搜索引擎进行安全、私密的网络搜索" },
    "ja": { "name": "DuckDuckGo検索", "type": "検索ツール", "description": "DuckDuckGo検索エンジンを使用して安全でプライベートなウェブ検索を行います" }
  }
}

用法

1. 初始化默认配置：

   uv run scripts/init_config.py
   

2. 修改 backend/config/ 下的 JSON 文件以添加或更新模型和端点。
3. 重启后端服务器以应用更改。

🔧 环境变量

后端（.env）

键	描述	默认值
DATABASE_URL	PostgreSQL 连接 URL	必需
BACKEND_CORS_ORIGINS	允许的 CORS 源（逗号分隔）	[]
MCP_SERVERS	SSE MCP 服务器端点的 JSON 列表	必需
SECRET_KEY	JWT 密钥	必需

前端（lib/core/config/app_config.dart）

static String get baseUrl => "http://127.0.0.1:8000";

💡 用法

1. 按照快速开始中的说明启动后端和前端。
2. 在浏览器或移动模拟器中打开应用。
3. 注册或登录以获取 JWT 令牌。
4. 使用深度思考模式或默认聊天模式与 AI Agent 互动。
5. 在设置中切换 MCP 服务或添加新端点。

🔗 API 参考

访问交互式 Swagger UI：

http://127.0.0.1:8000/docs

🛣️ 路线图

• SSE 多服务器支持
• 多语言支持（EN、中文、日本語）
• Docker Compose 设置
• 可流式传输的 HTTP 支持
• 本地 Stdio 多服务器支持
• 本地 OCR 支持
• 支持更多上传接口格式
• 前端自定义提示词
• 更多模型支持
• 更多语言支持

🛡️ 安全性

• 身份验证：所有后端端点均通过 JWT 保护；令牌安全存储在加密存储中。
• 数据保护：在生产环境中使用 HTTPS；通过 .env 中的 BACKEND_CORS_ORIGINS 配置允许的 CORS 源。
• 密钥管理：在 .env 中定义 SECRET_KEY；确保不向源控制提交任何密钥。

🔍 监控和日志

• 服务器日志：在 gunicorn.conf.py 中配置；访问和错误日志在 logs/ 中。
• 应用程序日志：使用 Loguru 进行结构化日志记录；前端在发布模式下禁用 debugPrint。

🚀 性能和优化

• 缓存：前端缓存静态资源；后端为 PostgreSQL 使用异步连接池。
• 包大小：网络制品使用 --wasm 构建以实现优化交付。

🗂️ 更新日志

所有重要更改都在 CHANGELOG.md 中记录。

📱 截图

🤝 贡献

欢迎贡献！请提交拉取请求以提出您的建议。

📄 许可证

本项目采用 CarrotAI 开源许可证。详见 LICENSE 文件。