# pyOllamaWebUi

**Repository Path**: chenchuhan/py-ollama-web-ui

## Basic Information

- **Project Name**: pyOllamaWebUi
- **Description**: 一个基于 Web 的聊天界面，可与 Ollama 模型进行交互，具有实时流式响应、聊天历史管理和模型选择功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-09
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!--
 * @Author: 陈楚汉 122090024@qq.com
 * @Date: 2026-01-08 12:55:21
 * @FilePath: \pyOllamaWebUi\README.md
 * @Description: 这是默认设置,请设置`customMade`, 打开koroFileHeader查看配置 进行设置: https://github.com/OBKoro1/koro1FileHeader/wiki/%E9%85%8D%E7%BD%AE
-->

# Ollama 聊天 Web 界面

一个基于 Web 的聊天界面，可与 Ollama 模型进行交互，具有实时流式响应、聊天历史管理和模型选择功能。

## 功能特点

- 来自 Ollama 模型的实时流式响应
- 聊天历史管理（创建、查看、删除聊天）
- 模型选择下拉菜单
- 将聊天对话导出为 JSON
- 适用于桌面和移动设备的响应式设计
- SQLite 数据库用于存储聊天历史
- WebSocket 支持流式响应

## 系统要求

- Python 3.8+
- Ollama 运行在 `http://172.16.1.68:11434`（默认地址）
- Ollama 中有可用的模型

## 安装步骤

### 1. 克隆仓库

```bash
git clone <repository-url>
cd ollama-chat-webui
```

### 2. 创建虚拟环境

```bash
# Linux/Mac系统
python3 -m venv venv
source venv/bin/activate

# Windows系统
python -m venv venv
venv\Scripts\activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 启动应用程序

```bash
# Linux/Mac系统
./run.sh

# Windows系统
run.bat
```

应用程序将在 `http://localhost:8000` 上访问。

## 配置

### Ollama API 地址配置

应用程序默认期望 Ollama 运行在 `http://localhost:11434`。如果您的 Ollama 实例运行在不同的地址，可以通过以下方式配置：

1. **环境变量方式（推荐）**：

   ```bash
   # 设置环境变量
   export OLLAMA_API_URL=http://your-ollama-server:11434/api
   ```

2. **复制示例配置文件**：
   ```bash
   cp .env.example .env
   # 编辑 .env 文件以匹配您的 Ollama 服务器地址
   ```

注意：如果您使用 .env 文件配置，需要先安装 `python-dotenv` 包：

```bash
pip install python-dotenv
```

此依赖已包含在 `requirements.txt` 中。

3. **直接修改源码**（不推荐）：
   如果以上方式不可用，可以直接修改 `backend/ollama_api.py` 中的 `OLLAMA_API_URL` 常量。

## 宝塔面板部署

### 1. 服务器设置

1. 在 Linux 服务器上安装宝塔面板
2. 通过宝塔面板安装 Python 环境
3. 将项目文件上传到服务器

### 2. 虚拟环境设置

1. SSH 连接到服务器或使用宝塔终端
2. 导航到项目目录
3. 创建并激活虚拟环境：

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 3. 进程管理

#### 方案 A：使用宝塔进程管理器

1. 在宝塔面板中，进入"软件商店"
2. 安装"Supervisor"或类似的进程管理器
3. 将 FastAPI 应用程序添加为受管进程：

```ini
[program:ollama-chat]
command=/path/to/your/venv/bin/uvicorn backend.main:app --host 0.0.0.0 --port 8000
directory=/path/to/your/project
autostart=true
autorestart=true
stdout_logfile=/var/log/ollama-chat.log
stderr_logfile=/var/log/ollama-chat-error.log
user=www
```

#### 方案 B：使用 Systemd（高级）

创建 systemd 服务文件：

```bash
sudo nano /etc/systemd/system/ollama-chat.service
```

添加以下内容：

```ini
[Unit]
Description=Ollama 聊天 WebUI
After=network.target

[Service]
Type=simple
User=www
WorkingDirectory=/path/to/your/project
Environment=PATH=/path/to/your/venv/bin
ExecStart=/path/to/your/venv/bin/uvicorn backend.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
```

启用并启动服务：

```bash
sudo systemctl daemon-reload
sudo systemctl enable ollama-chat
sudo systemctl start ollama-chat
```

### 4. Nginx 配置

1. 在宝塔面板中，添加新站点
2. 将域名指向项目目录
3. 配置反向代理，将请求转发到 FastAPI 应用程序：

```
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket支持
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
```

### 5. 自动启动

确保服务器重启后应用程序自动启动：

1. 使用上述 Supervisor 或 systemd 设置
2. 或创建宝塔计划任务，在启动时运行启动脚本

## 使用方法

1. 打开浏览器并导航到应用程序 URL
2. 从下拉菜单中选择模型
3. 在输入字段中键入消息，按 Enter 键或单击发送
4. 查看 AI 模型的流式响应
5. 使用侧边栏管理聊天历史

## API 端点

- `GET /` - 根端点
- `GET /chat/models` - 获取可用的 Ollama 模型
- `POST /chat/create?title={title}` - 创建新聊天
- `GET /chat/history` - 获取所有聊天历史
- `GET /chat/{chat_id}` - 获取特定聊天
- `DELETE /chat/{chat_id}` - 删除聊天
- `PUT /chat/{chat_id}/model?model={model}` - 为聊天设置模型
- `POST /chat/{chat_id}/send?message={message}&model={model}` - 发送消息
- `GET /chat/{chat_id}/export` - 导出聊天为 JSON
- `WS /ws/{chat_id}` - WebSocket 流式响应

## 开放平台 API (Public API)

提供标准的 RESTful 接口，方便第三方应用集成最核心的 AI 对话能力。

### 0. 基础规范

- **接口请求地址**：`http://your-server:8000/api`
- **默认返回格式**：

```json
{
  "code": 0,    // 0: 成功, 其他: 失败
  "message": "success",
  "data": {}
}
```

- **鉴权方式**：
  - 获取 API Key 时无需鉴权。
  - 其它接口需在 Header 中携带 `Authorization: Bearer <API_KEY>`。

### 1. 获取 API Key

通过用户名和密码获取 API Key。每个用户拥有唯一的 API Key。

- **接口地址**: `/api/key`
- **请求方式**: `GET`
- **请求参数**:
  - `username` (string, required): 用户名
  - `password` (string, required): 密码

**请求示例**:

```http
GET /api/key?username=myuser&password=mypassword HTTP/1.1
Host: localhost:8000
```

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "api_key": "sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}
```

### 2. 获取模型列表

查询当前系统可用的 AI 模型列表。

- **接口地址**: `/api/v1/models`
- **请求方式**: `GET`
- **鉴权**: Bearer Token

**请求示例**:

```http
GET /api/v1/models HTTP/1.1
Host: localhost:8000
Authorization: Bearer sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "models": [
      "llama3",
      "gemma:2b",
      "mistral"
    ]
  }
}
```

### 3. AI 对话 (非流式)

调用指定模型进行对话，一次性返回完整回复（非流式）。此接口不涉及会话上下文管理，适合单轮问答或自行管理上下文的场景。

- **接口地址**: `/api/v1/chat`
- **请求方式**: `POST`
- **鉴权**: Bearer Token
- **Content-Type**: `application/json`

**请求参数 (Body)**:

| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `model` | string | 是 | 模型名称，如 `llama3` |
| `prompt` | string | 是 | 对话内容/提示词 |

**请求示例**:

```json
{
  "model": "llama3",
  "prompt": "你好，请用简短的语言介绍一下自己。"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "model": "llama3",
    "reply": "你好！我是一个大型语言模型，由 Meta AI 训练。我可以协助你完成各种任务，如回答问题、提供建议、翻译文本等。"
  }
}
```

- **在线文档**: 启动服务后访问 `/docs` 可查看完整的 Swagger UI 文档。

## 项目结构

```
├── backend/
│   ├── db.py              # 数据库操作
│   ├── ollama_api.py      # Ollama API集成
│   └── main.py           # FastAPI应用程序
├── frontend/
│   └── index.html        # 主HTML文件
├── static/
│   ├── style.css         # 样式
│   └── script.js         # 前端JavaScript
├── chat.db               # SQLite数据库（自动创建）
├── requirements.txt      # Python依赖
├── run.sh/run.bat        # 启动脚本
└── README.md            # 此文件
```

## 故障排除

### 常见问题

1. **连接 Ollama API 被拒绝**

   - 确保 Ollama 在配置的地址上运行
   - 如果 Ollama 在不同机器上，请检查防火墙设置

2. **WebSocket 连接失败**

   - 验证反向代理是否支持 WebSocket 连接
   - 检查升级头是否正确配置

3. **应用程序无法启动**
   - 确保所有依赖项都已安装
   - 检查虚拟环境是否已激活

### 日志

检查应用程序日志中的错误：

```bash
# 如果使用systemd
sudo journalctl -u ollama-chat -f

# 如果使用supervisor
tail -f /var/log/ollama-chat.log
```

## 安全注意事项

- 如需要，使用身份验证限制对应用程序的访问
- 在生产环境中使用 HTTPS
- 验证和清理所有输入
- 定期更新依赖项

## 开发

要在开发模式下运行并启用自动重载：

```bash
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
```

## 许可证

MIT 许可证 - 可自由修改和分发。