From a869d884b75c07e5b69382ee120924b080e62be2 Mon Sep 17 00:00:00 2001 From: root <953994191@qq.com> Date: Wed, 22 Apr 2026 00:43:06 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E8=B7=AF=E5=BE=84=E5=BC=95=E7=94=A8=EF=BC=8C=E7=A7=BB=E9=99=A4?= =?UTF-8?q?=E7=A1=AC=E7=BC=96=E7=A0=81=E5=AF=86=E9=92=A5=EF=BC=8C=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=20Docker=20=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- QUICKSTART.md | 21 +++-- README.md | 157 ++++++++++++++++++++---------------- backend/app/rag/reranker.py | 2 +- docker/backend/Dockerfile | 2 +- docker/frontend/Dockerfile | 2 +- rag_indexer/clear_qdrant.py | 15 +++- scripts/start.sh | 16 ++-- 7 files changed, 125 insertions(+), 90 deletions(-) diff --git a/QUICKSTART.md b/QUICKSTART.md index 7d1cda8..f8c1a31 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -106,7 +106,7 @@ 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 +DB_URI=postgresql://postgres:your_password_here@115.190.121.151:5432/langgraph_db?sslmode=disable QDRANT_URL=http://115.190.121.151:6333 # 日志和调试 @@ -119,12 +119,17 @@ MEMORY_SUMMARIZE_INTERVAL=10 **终端 1 - 后端：** ```bash -python app/backend.py +python backend/app/backend.py ``` **终端 2 - 前端：** ```bash -streamlit run frontend/frontend_main.py +streamlit run frontend/src/frontend_main.py +``` + +或者使用启动脚本（推荐）： +```bash +./scripts/start.sh both ``` 浏览器自动打开前端页面，访问 http://127.0.0.1:8501 @@ -137,9 +142,9 @@ streamlit run frontend/frontend_main.py | 文件 | 用途 | |------|------| -| `docker-compose.yml` | 服务编排配置（包含 backend 和 frontend） | -| `Dockerfile.backend` | 后端镜像构建 | -| `Dockerfile.frontend` | 前端镜像构建 | +| `docker/docker-compose.yml` | 服务编排配置（包含 backend 和 frontend） | +| `docker/backend/Dockerfile` | 后端镜像构建 | +| `docker/frontend/Dockerfile` | 前端镜像构建 | | `.gitea/workflows/deploy.yml` | CI/CD 自动化部署 | ### docker-compose.yml 结构 @@ -173,7 +178,7 @@ docker compose up -d frontend ### 添加新工具 -在 [app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/app/graph/graph_tools.py) 中添加： +在 [backend/app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/backend/app/graph/graph_tools.py) 中添加： ```python @tool @@ -195,7 +200,7 @@ def my_new_tool(param: str) -> str: ### 添加新模型 -在 [app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/app/agent/llm_factory.py) 中： +在 [backend/app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/backend/app/agent/llm_factory.py) 中： ```python @staticmethod diff --git a/README.md b/README.md index 6ab1958..156f751 100644 --- a/README.md +++ b/README.md @@ -169,59 +169,73 @@ stateDiagram-v2 ``` Agent1/ -├── app/ -│ ├── __init__.py -│ ├── config.py # 配置管理 -│ ├── logger.py # 日志工具 -│ ├── backend.py # FastAPI 后端应用 -│ ├── agent/ +├── backend/ +│ ├── app/ │ │ ├── __init__.py -│ │ ├── service.py # Agent 服务核心 -│ │ ├── llm_factory.py # LLM 工厂 -│ │ ├── history.py # 历史查询服务 -│ │ ├── prompts.py # 提示模板 -│ │ └── rag_initializer.py # RAG 工具初始化 -│ ├── graph/ -│ │ ├── __init__.py -│ │ ├── graph_builder.py # LangGraph 图构建器 -│ │ ├── graph_tools.py # 工具定义 -│ │ ├── state.py # 状态定义 -│ │ └── retrieve_memory.py # 记忆检索 -│ ├── nodes/ -│ │ ├── __init__.py -│ │ ├── router.py # 路由决策 -│ │ ├── llm_call.py # LLM 调用节点 -│ │ ├── tool_call.py # 工具执行节点 -│ │ ├── retrieve_memory.py # 记忆检索节点 -│ │ ├── summarize.py # 记忆存储节点 -│ │ ├── finalize.py # 最终处理节点 -│ │ └── memory_trigger.py # 记忆触发节点 -│ ├── memory/ -│ │ ├── __init__.py -│ │ └── mem0_client.py # Mem0 客户端封装 -│ ├── rag/ -│ │ ├── __init__.py -│ │ ├── retriever.py # 检索器 -│ │ ├── reranker.py # 重排序 -│ │ ├── query_transform.py # 查询转换 -│ │ ├── pipeline.py # RAG 流水线 -│ │ ├── fusion.py # RAG-Fusion -│ │ └── tools.py # RAG 工具 -│ └── utils/ -│ └── __init__.py -├── frontend/ -│ ├── __init__.py -│ ├── frontend_main.py # Streamlit 主入口 -│ ├── api_client.py # API 客户端 -│ ├── config.py # 前端配置 -│ ├── state.py # 状态管理 -│ ├── logger.py # 日志 -│ ├── utils.py # 工具函数 -│ └── components/ +│ │ ├── config.py # 配置管理 +│ │ ├── logger.py # 日志工具 +│ │ ├── backend.py # FastAPI 后端应用 +│ │ ├── agent/ +│ │ │ ├── __init__.py +│ │ │ ├── service.py # Agent 服务核心 +│ │ │ ├── llm_factory.py # LLM 工厂 +│ │ │ ├── history.py # 历史查询服务 +│ │ │ ├── prompts.py # 提示模板 +│ │ │ └── rag_initializer.py # RAG 工具初始化 +│ │ ├── graph/ +│ │ │ ├── __init__.py +│ │ │ ├── graph_builder.py # LangGraph 图构建器 +│ │ │ ├── graph_tools.py # 工具定义 +│ │ │ ├── state.py # 状态定义 +│ │ │ └── retrieve_memory.py # 记忆检索 +│ │ ├── nodes/ +│ │ │ ├── __init__.py +│ │ │ ├── router.py # 路由决策 +│ │ │ ├── llm_call.py # LLM 调用节点 +│ │ │ ├── tool_call.py # 工具执行节点 +│ │ │ ├── retrieve_memory.py # 记忆检索节点 +│ │ │ ├── summarize.py # 记忆存储节点 +│ │ │ ├── finalize.py # 最终处理节点 +│ │ │ └── memory_trigger.py # 记忆触发节点 +│ │ ├── memory/ +│ │ │ ├── __init__.py +│ │ │ └── mem0_client.py # Mem0 客户端封装 +│ │ ├── rag/ +│ │ │ ├── __init__.py +│ │ │ ├── retriever.py # 检索器 +│ │ │ ├── reranker.py # 重排序 +│ │ │ ├── query_transform.py # 查询转换 +│ │ │ ├── pipeline.py # RAG 流水线 +│ │ │ ├── fusion.py # RAG-Fusion +│ │ │ └── tools.py # RAG 工具 +│ │ └── utils/ +│ │ └── __init__.py +│ └── rag_core/ │ ├── __init__.py -│ ├── sidebar.py # 侧边栏组件 -│ ├── chat_area.py # 聊天区域组件 -│ └── info_panel.py # 信息面板组件 +│ ├── client.py # RAG 核心客户端 +│ ├── embedders.py # 嵌入模型 +│ ├── vector_store.py # 向量存储 +│ ├── retriever_factory.py # 检索器工厂 +│ └── store/ +│ ├── __init__.py +│ ├── factory.py # 存储工厂 +│ └── postgres.py # PostgreSQL 存储 +├── frontend/ +│ ├── run.py # 前端启动脚本 +│ ├── requirements.txt +│ └── src/ +│ ├── __init__.py +│ ├── frontend_main.py # Streamlit 主入口 +│ ├── api_client.py # API 客户端 +│ ├── config.py # 前端配置 +│ ├── state.py # 状态管理 +│ ├── logger.py # 日志 +│ ├── utils.py # 工具函数 +│ └── components/ +│ ├── __init__.py +│ ├── sidebar.py # 侧边栏组件 +│ ├── chat_area.py # 聊天区域组件 +│ └── info_panel.py # 信息面板组件 ├── rag_indexer/ │ ├── __init__.py │ ├── cli.py # 命令行入口 @@ -229,22 +243,20 @@ Agent1/ │ ├── loaders.py # 文档加载器 │ ├── splitters.py # 文本切分器 │ └── test/ # 测试脚本 -├── rag_core/ -│ ├── __init__.py -│ ├── client.py # RAG 核心客户端 -│ ├── embedders.py # 嵌入模型 -│ ├── vector_store.py # 向量存储 -│ ├── retriever_factory.py # 检索器工厂 -│ └── store/ -│ ├── __init__.py -│ ├── factory.py # 存储工厂 -│ └── postgres.py # PostgreSQL 存储 ├── docker/ │ ├── docker-compose.yml # Docker 服务编排 -│ ├── Dockerfile.backend # 后端镜像构建 -│ └── Dockerfile.frontend # 前端镜像构建 +│ ├── backend/ +│ │ └── Dockerfile # 后端镜像构建 +│ ├── frontend/ +│ │ └── Dockerfile # 前端镜像构建 +│ └── models/ # spaCy 模型文件 ├── scripts/ │ └── start.sh # 启动脚本 +├── test/ # 测试目录 +│ ├── test_backend.py +│ ├── test_rag.py +│ ├── test_dqrant.py +│ └── test_rag_indexer_result.py ├── .gitea/ │ └── workflows/ │ └── deploy.yml # CI/CD 自动化部署 @@ -584,7 +596,7 @@ RAG 系统分为两个独立但协同的阶段： │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ -│ 阶段二：在线检索生成 (app/rag) │ +│ 阶段二：在线检索生成 (backend/app/rag) │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ 用户查询 → 查询改写 → 多路检索 → RRF 融合 → 重排序 │ │ │ │ MultiQuery Dense+Sparse Cross-Encoder │ │ @@ -803,10 +815,13 @@ cp .env.docker .env # 编辑 .env，根据本地/远程环境调整配置 # 3. 启动后端 -python app/backend.py +python backend/app/backend.py # 4. 启动前端（新终端） -streamlit run frontend/frontend_main.py +streamlit run frontend/src/frontend_main.py + +# 或者使用启动脚本（推荐） +./scripts/start.sh both ``` --- @@ -851,7 +866,7 @@ streamlit run frontend/frontend_main.py ### 添加新工具 -在 [app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/app/graph/graph_tools.py) 中添加新的 `@tool` 装饰函数： +在 [backend/app/graph/graph_tools.py](file:///home/huang/Study/AIProject/Agent1/backend/app/graph/graph_tools.py) 中添加新的 `@tool` 装饰函数： ```python @tool @@ -873,7 +888,7 @@ def my_new_tool(param: str) -> str: ### 添加新模型 -在 [app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/app/agent/llm_factory.py) 中添加模型创建方法： +在 [backend/app/agent/llm_factory.py](file:///home/huang/Study/AIProject/Agent1/backend/app/agent/llm_factory.py) 中添加模型创建方法： ```python @staticmethod @@ -1096,7 +1111,7 @@ curl -X POST http://localhost:6333/collections/my_docs/actions \ #### 3.1 添加自定义工具 ```python -# 在 app/graph/graph_tools.py 中添加 +# 在 backend/app/graph/graph_tools.py 中添加 from langchain_core.tools import tool from typing import Optional @@ -1154,7 +1169,7 @@ def calculate_expression( #### 3.2 添加自定义 LLM 提供商 ```python -# 在 app/agent/llm_factory.py 中添加 +# 在 backend/app/agent/llm_factory.py 中添加 from langchain_openai import ChatOpenAI from langchain_core.language_models import BaseChatModel @@ -1186,7 +1201,7 @@ class LLMFactory: #### 3.3 添加自定义 RAG 检索器 ```python -# 在 app/rag/retriever.py 中添加 +# 在 backend/app/rag/retriever.py 中添加 from langchain_core.retrievers import BaseRetriever from langchain_core.documents import Document diff --git a/backend/app/rag/reranker.py b/backend/app/rag/reranker.py index 925e283..b077d35 100644 --- a/backend/app/rag/reranker.py +++ b/backend/app/rag/reranker.py @@ -20,7 +20,7 @@ class LLaMaCPPReranker: Args: base_url: llama.cpp 服务的地址和端口，默认为环境变量 LLAMACPP_RERANKER_URL 或 "http://127.0.0.1:8083"。 top_n: 返回前 N 个结果。 - api_key: API 密钥，默认为环境变量 LLAMACPP_API_KEY 或 "huang1998"。 + api_key: API 密钥，默认为环境变量 LLAMACPP_API_KEY 。 timeout: 请求超时时间（秒）。 """ self.base_url = base_url diff --git a/docker/backend/Dockerfile b/docker/backend/Dockerfile index aeb8c74..2bb8bfd 100644 --- a/docker/backend/Dockerfile +++ b/docker/backend/Dockerfile @@ -86,4 +86,4 @@ EXPOSE 8079 # ============================================================================= # 启动命令 # ============================================================================= -CMD ["python", "app/backend.py"] +CMD ["python", "-m", "app.backend"] diff --git a/docker/frontend/Dockerfile b/docker/frontend/Dockerfile index ef1c547..f29fa5c 100644 --- a/docker/frontend/Dockerfile +++ b/docker/frontend/Dockerfile @@ -18,4 +18,4 @@ COPY frontend/src/ ./src/ EXPOSE 8501 # 启动命令 -CMD ["streamlit", "run", "src/frontend_main.py", "--server.port", "8501", "--server.address", "0.0.0.0", "--server.baseUrlPath", "/ai"] +CMD ["streamlit", "run", "src.frontend_main", "--server.port", "8501", "--server.address", "0.0.0.0", "--server.baseUrlPath", "/ai"] diff --git a/rag_indexer/clear_qdrant.py b/rag_indexer/clear_qdrant.py index 7c6a793..4439f6e 100644 --- a/rag_indexer/clear_qdrant.py +++ b/rag_indexer/clear_qdrant.py @@ -13,9 +13,20 @@ import argparse from dotenv import load_dotenv load_dotenv() -QDRANT_URL = os.getenv("QDRANT_URL", "http://127.0.0.1:6333") +QDRANT_URL = os.getenv("QDRANT_URL") QDRANT_API_KEY = os.getenv("QDRANT_API_KEY") -DB_URI = os.getenv("DB_URI", "postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable") + +# PostgreSQL 配置（使用分离配置，优先于 DB_URI） +DB_HOST = os.getenv("DB_HOST") +DB_PORT = os.getenv("DB_PORT", "5432") +DB_USER = os.getenv("DB_USER") +DB_PASSWORD = os.getenv("DB_PASSWORD") +DB_NAME = os.getenv("DB_NAME") + +# 构建 DB_URI（如果没有直接配置） +DB_URI = os.getenv("DB_URI") +if not DB_URI and all([DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME]): + DB_URI = f"postgresql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}?sslmode=disable" COLLECTION_NAME = "rag_documents" TABLE_NAME = "parent_documents" diff --git a/scripts/start.sh b/scripts/start.sh index bf39a0a..6edc2b2 100755 --- a/scripts/start.sh +++ b/scripts/start.sh @@ -145,13 +145,17 @@ check_config() { echo "" echo "🌐 检查远程服务连接..." - # 测试 PostgreSQL 连接 + # 测试 PostgreSQL 连接（从环境变量读取密码） if command -v psql &> /dev/null; then - if PGPASSWORD=huang1998 psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT 1;" &> /dev/null; then - check_pass "PostgreSQL 远程连接正常 (115.190.121.151:5432)" + if [ -n "$DB_PASSWORD" ]; then + if PGPASSWORD="$DB_PASSWORD" psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT 1;" &> /dev/null; then + check_pass "PostgreSQL 远程连接正常 (115.190.121.151:5432)" + else + check_fail "PostgreSQL 远程连接失败" + echo " 提示: 检查网络连接和防火墙设置" + fi else - check_fail "PostgreSQL 远程连接失败" - echo " 提示: 检查网络连接和防火墙设置" + check_warn "DB_PASSWORD 未配置，跳过 PostgreSQL 连接测试" fi else check_warn "psql 客户端未安装，跳过 PostgreSQL 连接测试" @@ -267,7 +271,7 @@ start_embedding() { -e LLAMA_ARG_N_PARALLEL=1 \ -e LLAMA_ARG_BATCH=512 \ -e LLAMA_ARG_N_GPU_LAYERS=99 \ - -e LLAMA_ARG_API_KEY=huang1998 \ + -e LLAMA_ARG_API_KEY="$LLAMACPP_API_KEY" \ ghcr.io/ggml-org/llama.cpp:server-rocm \ -m /models/Qwen3-Embedding-0.6B-Q8_0.gguf \ --host 0.0.0.0 \