This commit is contained in:
118
QUICKSTART.md
118
QUICKSTART.md
@@ -22,15 +22,17 @@ vim .env # 或使用你喜欢的编辑器
|
||||
|
||||
**必需配置项**：
|
||||
- `ZHIPUAI_API_KEY` - 智谱 AI API 密钥（从 [智谱开放平台](https://open.bigmodel.cn/) 获取）
|
||||
- `DEEPSEEK_API_KEY` - DeepSeek API 密钥（从 [DeepSeek 开放平台](https://platform.deepseek.com/) 获取）
|
||||
- `LLAMACPP_API_KEY` - llama.cpp 服务认证 Token（与容器启动参数一致，默认 `token-abc123`）
|
||||
|
||||
**可选配置项**：
|
||||
- `VLLM_BASE_URL` - LLM 服务地址（本地默认：`http://127.0.0.1:8081/v1`，Docker容器访问宿主机：`http://host.docker.internal:18000/v1`）
|
||||
- `LLAMACPP_EMBEDDING_URL` - Embedding 服务地址（本地默认：`http://127.0.0.1:8082/v1`，Docker容器访问宿主机：`http://host.docker.internal:18001/v1`）
|
||||
- `DB_URI` - PostgreSQL 连接字符串（默认已配置，使用远程服务器地址）
|
||||
- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置，使用远程服务器地址）
|
||||
|
||||
**注意**：Docker Compose 部署时，`API_URL` 由 `docker-compose.yml` 自动注入，无需在 `.env` 中配置。
|
||||
- `VLLM_BASE_URL` - LLM 服务地址（本地默认：`http://127.0.0.1:8081/v1`）
|
||||
- `LLAMACPP_EMBEDDING_URL` - Embedding 服务地址（本地默认：`http://127.0.0.1:8082/v1`）
|
||||
- `DB_URI` - PostgreSQL 连接字符串（默认已配置远程服务器地址）
|
||||
- `QDRANT_URL` - Qdrant 向量数据库地址（默认已配置远程服务器地址）
|
||||
- `LOG_LEVEL` - 日志级别（`DEBUG`/`INFO`/`WARNING`/`ERROR`）
|
||||
- `ENABLE_GRAPH_TRACE` - 是否启用图流转追踪（`true`/`false`）
|
||||
- `MEMORY_SUMMARIZE_INTERVAL` - 对话摘要生成间隔（默认 `10`）
|
||||
|
||||
#### 2. 启动服务
|
||||
|
||||
@@ -40,12 +42,9 @@ docker compose -f docker/docker-compose.yml up -d --build
|
||||
|
||||
#### 3. 访问应用
|
||||
|
||||
**如果配置了 Nginx 反向代理**：
|
||||
- 访问地址：`http://your-domain.com` 或 `http://your-server-ip`
|
||||
|
||||
**如果未配置 Nginx（直接访问容器）**：
|
||||
- **前端**: http://127.0.0.1:8501
|
||||
- **后端 API**: http://127.0.0.1:8001
|
||||
- **后端 API**: http://127.0.0.1:8083
|
||||
- **健康检查**: http://127.0.0.1:8083/health
|
||||
|
||||
#### 常用命令
|
||||
|
||||
@@ -56,11 +55,17 @@ docker compose ps
|
||||
# 查看日志
|
||||
docker compose logs -f
|
||||
|
||||
# 查看特定服务日志
|
||||
docker compose logs -f backend
|
||||
|
||||
# 重启特定服务
|
||||
docker compose restart backend
|
||||
|
||||
# 停止所有服务
|
||||
docker compose down
|
||||
|
||||
# 重新构建并启动
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
---
|
||||
@@ -83,31 +88,31 @@ pip install -r requirement.txt
|
||||
|
||||
复制并编辑 `.env` 文件：
|
||||
|
||||
```
|
||||
# 基于 Docker 模板创建
|
||||
```bash
|
||||
cp .env.docker .env
|
||||
vim .env
|
||||
```
|
||||
|
||||
**本地开发需要修改以下配置**：
|
||||
**本地开发配置示例**：
|
||||
|
||||
``env
|
||||
```env
|
||||
# API Keys
|
||||
ZHIPUAI_API_KEY=your_api_key_here
|
||||
DEEPSEEK_API_KEY=your_deepseek_api_key_here
|
||||
LLAMACPP_API_KEY=token-abc123
|
||||
|
||||
# 本地开发时，llama.cpp 服务在 127.0.0.1
|
||||
VLLM_BASE_URL=http://127.0.0.1:8081/v1 # 本地开发
|
||||
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1 # 本地开发
|
||||
# 或
|
||||
VLLM_BASE_URL=http://host.docker.internal:18000/v1 # Docker容器访问宿主机
|
||||
LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1 # Docker容器访问宿主机
|
||||
# LLM 服务地址（本地开发）
|
||||
VLLM_BASE_URL=http://127.0.0.1:8081/v1
|
||||
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1
|
||||
|
||||
# 数据库和向量存储使用远程服务器
|
||||
# 远程数据库和向量存储
|
||||
DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
|
||||
QDRANT_URL=http://115.190.121.151:6333
|
||||
|
||||
# 本地开发时，后端也在 127.0.0.1
|
||||
API_URL=http://127.0.0.1:8083/chat
|
||||
# 日志和调试
|
||||
LOG_LEVEL=INFO
|
||||
ENABLE_GRAPH_TRACE=true
|
||||
MEMORY_SUMMARIZE_INTERVAL=10
|
||||
```
|
||||
|
||||
#### 3. 启动服务
|
||||
@@ -119,10 +124,10 @@ python app/backend.py
|
||||
|
||||
**终端 2 - 前端：**
|
||||
```bash
|
||||
cd frontend && streamlit run app.py
|
||||
streamlit run frontend/frontend_main.py
|
||||
```
|
||||
|
||||
浏览器自动打开前端页面（如果配置了 Nginx，访问 `http://your-domain.com`；否则访问 http://127.0.0.1:8501）
|
||||
浏览器自动打开前端页面，访问 http://127.0.0.1:8501
|
||||
|
||||
---
|
||||
|
||||
@@ -132,7 +137,7 @@ cd frontend && streamlit run app.py
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `docker-compose.yml` | 服务编排配置（仅包含 backend 和 frontend） |
|
||||
| `docker-compose.yml` | 服务编排配置（包含 backend 和 frontend） |
|
||||
| `Dockerfile.backend` | 后端镜像构建 |
|
||||
| `Dockerfile.frontend` | 前端镜像构建 |
|
||||
| `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 |
|
||||
@@ -141,14 +146,16 @@ cd frontend && streamlit run app.py
|
||||
|
||||
```yaml
|
||||
services:
|
||||
backend: # FastAPI 后端服务（连接远程 PostgreSQL 和 Qdrant）
|
||||
frontend: # Streamlit 前端界面
|
||||
backend: # FastAPI 后端服务（端口 8083）
|
||||
frontend: # Streamlit 前端界面（端口 8501）
|
||||
```
|
||||
|
||||
**特性：**
|
||||
- ✅ 通过环境变量连接远程 PostgreSQL 和 Qdrant
|
||||
- ✅ 自动重启策略（`restart: unless-stopped`）
|
||||
- ✅ 内部网络隔离
|
||||
- ✅ 内部网络隔离（ai-network）
|
||||
- ✅ 文档目录挂载（`./data/user_docs`）
|
||||
- ✅ 日志目录挂载（`./logs`）
|
||||
|
||||
### 只更新特定服务
|
||||
|
||||
@@ -166,7 +173,7 @@ docker compose up -d frontend
|
||||
|
||||
### 添加新工具
|
||||
|
||||
在 `app/tools.py` 中添加：
|
||||
在 [app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/app/graph/graph_tools.py) 中添加：
|
||||
|
||||
```python
|
||||
@tool
|
||||
@@ -184,35 +191,34 @@ def my_new_tool(param: str) -> str:
|
||||
return result
|
||||
```
|
||||
|
||||
工具会自动注册，无需修改其他文件。
|
||||
工具会自动注册到 `AVAILABLE_TOOLS` 列表，无需修改其他文件。
|
||||
|
||||
### 添加新模型
|
||||
|
||||
在 `app/agent.py` 中：
|
||||
在 [app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/app/agent/llm_factory.py) 中：
|
||||
|
||||
```python
|
||||
def _create_new_model_llm(self):
|
||||
@staticmethod
|
||||
def create_new_model():
|
||||
"""创建新模型的 LLM"""
|
||||
return YourChatModel(
|
||||
api_key = os.getenv("NEW_MODEL_API_KEY")
|
||||
return ChatOpenAI(
|
||||
base_url="https://api.new-model.com/v1",
|
||||
api_key=SecretStr(api_key),
|
||||
model="model-name",
|
||||
api_key=os.getenv("YOUR_API_KEY"),
|
||||
temperature=0.1,
|
||||
streaming=True,
|
||||
)
|
||||
|
||||
# 在 initialize() 方法中注册
|
||||
model_configs = {
|
||||
"zhipu": self._create_zhipu_llm,
|
||||
"local": self._create_local_llm,
|
||||
"new_model": self._create_new_model_llm, # 新增
|
||||
}
|
||||
```
|
||||
|
||||
在前端 `frontend/app.py` 中添加选项：
|
||||
然后在 `CREATORS` 字典中注册：
|
||||
|
||||
```python
|
||||
MODEL_OPTIONS = {
|
||||
"智谱 GLM-4": "zhipu",
|
||||
"本地 Gemma-4": "local",
|
||||
"新模型": "new_model", # 新增
|
||||
CREATORS = {
|
||||
"local": create_local,
|
||||
"deepseek": create_deepseek,
|
||||
"zhipu": create_zhipu,
|
||||
"new_model": create_new_model, # 新增
|
||||
}
|
||||
```
|
||||
|
||||
@@ -226,7 +232,12 @@ docker compose exec backend bash
|
||||
docker compose logs -f backend
|
||||
|
||||
# 测试后端 API
|
||||
curl http://127.0.0.1:8001/health
|
||||
curl http://127.0.0.1:8083/health
|
||||
|
||||
# 测试对话接口
|
||||
curl -X POST http://127.0.0.1:8083/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "你好", "model": "zhipu"}'
|
||||
```
|
||||
|
||||
---
|
||||
@@ -252,6 +263,7 @@ curl http://127.0.0.1:8001/health
|
||||
|
||||
在 Gitea 仓库设置中添加：
|
||||
- `ZHIPUAI_API_KEY`
|
||||
- `DEEPSEEK_API_KEY`
|
||||
- `LLAMACPP_API_KEY`
|
||||
|
||||
---
|
||||
@@ -282,19 +294,19 @@ curl http://115.190.121.151:6333/collections
|
||||
docker compose logs backend
|
||||
|
||||
# 检查端口占用
|
||||
lsof -i :8001
|
||||
lsof -i :8083
|
||||
```
|
||||
|
||||
**常见原因：**
|
||||
- API Key 未配置或错误
|
||||
- 端口 8001 被占用
|
||||
- 端口 8083 被占用
|
||||
- 依赖包缺失
|
||||
|
||||
#### 3. 前端无法连接后端
|
||||
|
||||
**错误信息：**
|
||||
```
|
||||
HTTPConnectionPool(host='backend', port=8001): Max retries exceeded
|
||||
HTTPConnectionPool(host='backend', port=8083): Max retries exceeded
|
||||
```
|
||||
|
||||
**解决方案：**
|
||||
@@ -324,7 +336,7 @@ docker compose logs backend | grep -i "model\|error"
|
||||
```
|
||||
|
||||
**可能原因：**
|
||||
- 智谱 API Key 无效
|
||||
- 智谱/DeepSeek API Key 无效
|
||||
- vLLM 容器未启动（如使用本地模型）
|
||||
- 网络连接问题
|
||||
|
||||
|
||||
Reference in New Issue
Block a user