# MARS

**Repository Path**: seancheney/mars

## Basic Information

- **Project Name**: MARS
- **Description**: MARS：多智能体推荐系统
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能体推荐系统

基于对话式主动偏好询问的冷启动推荐系统

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React + Ant Design |
| 后端 | FastAPI (Python) |
| LLM 框架 | LangChain + LangGraph |
| 多智能体 | AutoGen |
| 大语言模型 | MiniMax M2.7 |
| 向量数据库 | Pinecone / Milvus |
| 图数据库 | Neo4j |
| 缓存 | Redis |
| 部署 | Docker + Kubernetes |

## 项目结构

```
MARS/
├── backend/              # FastAPI 后端
│   ├── app/
│   │   ├── agents/      # 核心智能体模块
│   │   │   ├── dialog_manager.py      # 对话状态机
│   │   │   ├── preference_extractor.py # 偏好抽取
│   │   │   ├── topic_selector.py      # 话题选择
│   │   │   ├── result_generator.py    # 推荐生成
│   │   │   ├── user_profile.py        # 用户画像
│   │   │   ├── langgraph/             # LangGraph 编排
│   │   │   └── autogen/               # AutoGen 多智能体
│   │   ├── services/
│   │   │   └── llm_service.py        # LLM 服务封装
│   │   ├── models/
│   │   │   └── schemas.py            # Pydantic 模型
│   │   └── main.py                   # FastAPI 入口
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/             # React 前端
│   ├── src/
│   │   ├── App.tsx      # 主组件
│   │   └── App.css      # 样式
│   ├── package.json
│   └── Dockerfile
├── k8s/                 # Kubernetes 配置
├── docker-compose.yml   # Docker Compose 编排
└── README.md
```

## 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone <repo-url>
cd MARS

# 复制环境变量
cp .env.example .env
# 编辑 .env 填入你的 API Key
```

### 2. 本地开发

```bash
# 启动后端
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# 启动前端（新终端）
cd frontend
npm install
npm run dev
```

### 3. Docker Compose

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止
docker-compose down
```

### 4. Kubernetes 部署

```bash
# 构建镜像
docker build -t mars-backend:latest ./backend
docker build -t mars-frontend:latest ./frontend

# 部署
kubectl apply -f k8s/

# 检查状态
kubectl get pods
kubectl get services
```

## 核心模块

### 对话状态机

```
INIT → INTERESTED → CLARIFYING → CONFIRM_READY → PROFILE_READY
```

| 状态 | 说明 |
|------|------|
| INIT | 初始化，询问用户兴趣领域 |
| INTERESTED | 用户已表达兴趣，继续深入询问 |
| CLARIFYING | 澄清偏好 |
| CONFIRM_READY | 确认用户画像 |
| PROFILE_READY | 画像构建完成，开始推荐 |

### 话题层级体系

```
科技: [人工智能, 手机数码, 新能源, 互联网, 芯片半导体]
财经: [股市, 基金, 宏观经济, 房地产, 原油黄金]
娱乐: [明星, 影视, 音乐, 综艺, 游戏]
体育: [足球, 篮球, 网球, 电竞, MMA]
国际: [中美关系, 欧洲, 东亚, 一带一路, 联合国]
社会: [教育, 医疗, 就业, 人口, 环境]
```

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /health | 健康检查 |
| POST | /api/v1/dialog/initialize | 初始化对话 |
| POST | /api/v1/dialog/message | 发送消息 |
| POST | /api/v1/recommendations | 获取推荐 |
| WS | /ws/dialog | WebSocket 对话 |

## 环境变量

```bash
# MiniMax LLM
MINIMAX_API_KEY=your_api_key
MINIMAX_BASE_URL=https://api.minimax.chat/v1
MINIMAX_MODEL=MoE

# Pinecone (可选，默认为内置示例)
PINECONE_API_KEY=your_pinecone_key

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
```

## 开发指南

### 添加新的智能体

1. 在 `app/agents/` 下创建新模块
2. 实现核心逻辑
3. 在 `app/main.py` 中注册

### 修改话题体系

编辑 `app/agents/user_profile.py` 中的 `TOPIC_HIERARCHY`

## License

MIT