# AChat

**Repository Path**: A_gua/achat

## Basic Information

- **Project Name**: AChat
- **Description**: 一个现代、开源、可自部署的 AI 对话 Web Demo，提供类似主流 AI 聊天网站的体验。 支持流式响应、多轮会话、Markdown 渲染、代码高亮、模型切换、会话历史与本地持久化，可接入任意 OpenAI 兼容 API。适合学习 LLM 应用开发、二次开发自己的 AI 聊天产品，或作为内部工具快速部署。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AChat

> 一个现代、开源、可自部署的 AI 对话 Web Demo，提供类似主流 AI 聊天网站的体验。

支持流式响应、多轮会话、Markdown 渲染、代码高亮、模型切换、会话历史与本地持久化，可接入任意 OpenAI 兼容 API。适合学习 LLM 应用开发、二次开发自己的 AI 聊天产品，或作为内部工具快速部署。

---

## ✨ 特性

- 🔒 **本地部署，隐私可控** — API Key 保存在本地 `config/config.yaml`，不上传服务器
- 💬 **流式对话** — SSE 实时逐字输出，可随时中止
- 🧩 **插件化架构** — 联网搜索、文档解析、图片生成、图像识别开箱即用，方便扩展
- 📚 **知识库 / RAG** — 上传 PDF / DOCX / TXT / MD，自动分片入库，对话时召回相关片段
- 🎯 **多模型切换** — 支持 OpenAI / DeepSeek / Ollama / 任意 OpenAI 兼容服务
- 🗂️ **会话历史** — SQLite 本地持久化，支持增删改查
- 🎨 **现代 UI** — React + TailwindCSS，Markdown 渲染、代码高亮、亮暗色主题

## 🛠 技术栈

| 层级 | 选型 |
|------|------|
| 前端 | React 18 · Vite · TypeScript · TailwindCSS · Zustand · react-markdown |
| 后端 | Python 3.10+ · FastAPI · SQLAlchemy · sse-starlette |
| AI   | OpenAI SDK · LangChain · ChromaDB · DuckDuckGo Search |
| 存储 | SQLite（对话） · ChromaDB（向量） · 本地 YAML（配置） |

## 📁 项目结构

```
AChat/
├── backend/                # Python FastAPI 后端
│   ├── app/
│   │   ├── main.py         # 应用入口
│   │   ├── config.py       # 配置加载
│   │   ├── api/            # 路由：chat / conversation / knowledge / tools
│   │   ├── core/           # LLM 封装、Prompt、SSE 流式
│   │   ├── plugins/        # 插件（web_search / doc_parser / image_gen / image_recog）
│   │   ├── rag/            # RAG：chunker / embedder / vectorstore / retriever
│   │   ├── models/         # ORM + Pydantic Schema
│   │   └── utils/          # 日志等工具
│   └── pyproject.toml
├── frontend/               # React + Vite 前端
│   ├── src/
│   │   ├── components/     # Sidebar / TopBar / ChatWindow / MessageBubble / ChatInput
│   │   ├── stores/         # Zustand 状态
│   │   ├── services/       # API 客户端（含 SSE）
│   │   └── types/
│   └── package.json
├── config/
│   ├── config.example.yaml # 示例配置（提交到 Git）
│   └── config.yaml         # 本地实际配置（.gitignore 排除）
├── data/                   # 运行时数据：SQLite / ChromaDB / 上传文件（.gitignore 排除）
├── scripts/
│   └── start.py            # 一键启动脚本
└── README.md
```

## 🚀 快速开始

### 前置要求

- Python 3.10+
- Node.js 18+（含 npm 或 pnpm）
- 一个 OpenAI 兼容的 LLM API Key（或本地 Ollama）

### 一键启动（推荐）

```powershell
# 1. 克隆项目
git clone <your-repo-url> AChat
cd AChat

# 2. 一键启动（首次会自动创建 venv、安装依赖、构建前端）
python scripts/start.py
```

启动后浏览器会自动打开 <http://127.0.0.1:8765>。

**常用参数：**

```powershell
python scripts/start.py --dev        # 开发模式：Vite dev server + 后端热重载
python scripts/start.py --rebuild    # 强制重新构建前端
python scripts/start.py --no-open    # 不自动打开浏览器
python scripts/start.py --port 9000  # 换端口
```

### 手动启动

```powershell
# 后端
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -e .
uvicorn app.main:app --host 127.0.0.1 --port 8765 --reload

# 前端（另开一个终端）
cd frontend
npm install
npm run dev          # 开发模式，访问 http://127.0.0.1:5173
# 或
npm run build        # 生产模式，构建到 frontend/dist，由后端一并 serve
```

### 配置 API Key

复制 `config/config.example.yaml` 为 `config/config.yaml`，填入你的 API Key：

```yaml
llm:
  default_provider: "openai"
  providers:
    openai:
      api_key: "sk-xxxxxxxxxxxxxxxx"
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o-mini"
```

也可以配置 DeepSeek、Ollama、或任意 OpenAI 兼容服务，然后在前端顶部下拉框切换。

## 🔌 API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET  | `/api/health` | 健康检查 |
| GET  | `/api/version` | 版本信息 |
| GET  | `/api/providers` | 可用的 LLM provider 列表 |
| GET  | `/api/plugins` | 已注册插件列表 |
| POST | `/api/plugins/invoke` | 调用插件 |
| POST | `/api/chat/completions` | **SSE 流式对话** |
| GET  | `/api/conversations` | 会话列表 |
| POST | `/api/conversations` | 创建会话 |
| GET  | `/api/conversations/{id}` | 会话详情（含消息） |
| PATCH| `/api/conversations/{id}` | 修改会话标题 |
| DELETE | `/api/conversations/{id}` | 删除会话 |
| GET  | `/api/knowledge/documents` | 知识库文档列表 |
| POST | `/api/knowledge/documents` | 上传文档到知识库 |
| POST | `/api/knowledge/query` | 测试召回 |
| GET  | `/api/knowledge/stats` | 知识库统计 |

启动后访问 <http://127.0.0.1:8765/api/docs> 查看交互式 Swagger 文档。

## 🧩 插件开发

在 `backend/app/plugins/` 下新建文件，继承 `BasePlugin` 并用 `@register` 装饰即可：

```python
from typing import Any, ClassVar
from app.plugins.base import BasePlugin, register

@register
class MyPlugin(BasePlugin):
    name: ClassVar[str] = "my_plugin"
    display_name: ClassVar[str] = "我的插件"
    description: ClassVar[str] = "插件功能描述"
    parameters_schema: ClassVar[dict] = {
        "type": "object",
        "properties": {"arg": {"type": "string"}},
        "required": ["arg"],
    }

    async def execute(self, arg: str = "", **_) -> dict[str, Any]:
        return {"ok": True, "data": {"echo": arg}}
```

然后在 `plugins/__init__.py` 的 `load_builtin_plugins()` 中 import 即可。

## 🗺 Roadmap

- [x] 基础对话（流式 / 多轮 / 会话持久化）
- [x] 插件框架 & 内置插件骨架
- [x] RAG 知识库（上传 / 分片 / 召回）
- [ ] Function Calling 自动路由插件
- [ ] 前端知识库管理页面
- [ ] 语音输入 / TTS
- [ ] 多模态对话（图片 + 文本）
- [ ] Prompt 人设模板市场
- [ ] 对话导出（Markdown / PDF）
- [ ] Token 用量统计与成本估算
- [ ] Docker 一键部署

## 📄 License

见 [LICENSE](./LICENSE)。