Spaces:
Sleeping
Sleeping
| title: AgenticRAG | |
| emoji: 🌖 | |
| colorFrom: pink | |
| colorTo: pink | |
| sdk: gradio | |
| sdk_version: 5.29.1 | |
| app_file: app.py | |
| pinned: false | |
| license: apache-2.0 | |
| # 🌖 AgenticRAG — Agentic RAG 智慧助理 | |
| > **Hugging Face Agents Course · Unit 3 — Agentic RAG** | |
| > | |
| > 結合 **Retrieval-Augmented Generation (RAG)** 與 **Agent（代理人）** 架構的智慧問答系統， | |
| > 部署於 [Hugging Face Spaces](https://huggingface.co/spaces)，透過 Gradio 提供互動式 Web UI。 | |
| --- | |
| ## 📖 目錄 | |
| - [專案簡介](#-專案簡介) | |
| - [系統架構](#-系統架構) | |
| - [功能與工具](#-功能與工具) | |
| - [檔案結構](#-檔案結構) | |
| - [安裝與執行](#-安裝與執行) | |
| - [環境變數](#-環境變數) | |
| - [使用範例](#-使用範例) | |
| - [技術棧](#-技術棧) | |
| - [授權條款](#-授權條款) | |
| --- | |
| ## 🧠 專案簡介 | |
| 本專案是 [Hugging Face Agents Course](https://huggingface.co/learn/agents-course) **Unit 3** 的實作作業。 | |
| 透過 `smolagents` 框架建立一個 **CodeAgent（程式碼代理人）**，名為 **Alfred**， | |
| 它能自主判斷要使用哪些工具，並以程式碼的方式組合執行，回答使用者的各種問題。 | |
| ### 核心概念 | |
| | 概念 | 說明 | | |
| |---|---| | |
| | **Agentic RAG** | Agent 在回答問題時，先透過 Retriever 從知識庫檢索相關資料，再結合 LLM 產生答案 | | |
| | **CodeAgent** | `smolagents` 的代理人類型，會產生並執行 Python 程式碼來完成任務 | | |
| | **Planning** | Agent 每 3 步驟進行一次規劃 (`planning_interval=3`)，確保多步驟推理的準確性 | | |
| --- | |
| ## 🏗 系統架構 | |
| ``` | |
| 使用者 (Gradio Web UI) | |
| │ | |
| ▼ | |
| ┌──────────────┐ | |
| │ CodeAgent │ ← Alfred（由 smolagents 驅動） | |
| │ (Qwen2.5) │ | |
| └──────┬───────┘ | |
| │ 根據問題自動選擇工具 | |
| ├──────────────────────────────┐ | |
| │ │ | |
| ┌────▼─────┐ ┌─────▼──────┐ | |
| │ 內建工具 │ │ 自訂工具 │ | |
| └──────────┘ └─────┬──────┘ | |
| │ | |
| ┌────────────┬────────────┼────────────┐ | |
| │ │ │ │ | |
| ┌─────▼─────┐ ┌───▼───┐ ┌─────▼─────┐ ┌───▼────────┐ | |
| │ GuestInfo │ │Weather│ │ HubStats │ │DuckDuckGo │ | |
| │ Retriever │ │ Info │ │ Tool │ │ Search │ | |
| └─────┬─────┘ └───────┘ └─────┬─────┘ └────────────┘ | |
| │ │ | |
| ▼ ▼ | |
| BM25 Retriever Hugging Face Hub | |
| (agents-course/ API | |
| unit3-invitees) | |
| ``` | |
| --- | |
| ## 🔧 功能與工具 | |
| ### 1. 🎭 賓客資訊檢索 (`guest_info_retriever`) | |
| - **檔案**：[`retriever.py`](retriever.py) | |
| - **類別**：`GuestInfoRetrieverTool` | |
| - **說明**：從 Hugging Face Datasets（`agents-course/unit3-invitees`）載入賓客資料， | |
| 使用 **BM25 演算法** 進行關鍵字檢索，回傳最相關的前 3 筆賓客資訊。 | |
| - **輸入**：賓客姓名或關係（`query: str`） | |
| - **輸出**：包含姓名、關係、描述、Email 的文字資訊 | |
| ### 2. 🌤 天氣查詢 (`weather_info`) | |
| - **檔案**：[`tools.py`](tools.py) | |
| - **類別**：`WeatherInfoTool` | |
| - **說明**：根據指定地點回傳模擬天氣資料（Rainy / Clear / Windy + 溫度）。 | |
| 目前為 **Demo 用途**，使用隨機產生的假資料。 | |
| - **輸入**：地點名稱（`location: str`） | |
| - **輸出**：天氣狀況與溫度字串 | |
| ### 3. 📊 Hub 模型統計 (`hub_stats`) | |
| - **檔案**：[`tools.py`](tools.py) | |
| - **類別**：`HubStatsTool` | |
| - **說明**：查詢指定作者／組織在 Hugging Face Hub 上下載量最高的模型。 | |
| - **輸入**：作者或組織名稱（`author: str`） | |
| - **輸出**：模型名稱與下載次數 | |
| ### 4. 🔍 DuckDuckGo 網頁搜尋 | |
| - **來源**：`smolagents.DuckDuckGoSearchTool`（內建工具） | |
| - **說明**：透過 DuckDuckGo 搜尋引擎進行網頁搜尋，取得即時資訊。 | |
| --- | |
| ## 📂 檔案結構 | |
| ``` | |
| Unit_3_Agentic_RAG/ | |
| ├── app.py # 主程式入口：初始化 Agent 與所有工具，啟動 Gradio UI | |
| ├── tools.py # 自訂工具：WeatherInfoTool、HubStatsTool | |
| ├── retriever.py # RAG 檢索器：GuestInfoRetrieverTool + 資料集載入 | |
| ├── requirements.txt # Python 套件依賴清單 | |
| ├── README.md # 本說明文件 | |
| ├── .gitattributes # Git LFS 設定（Hugging Face Spaces 標準配置） | |
| └── .gradio/ # Gradio 執行時快取（含 HTTPS 憑證等） | |
| ``` | |
| --- | |
| ## 🚀 安裝與執行 | |
| ### 前置需求 | |
| - Python 3.10+ | |
| - Hugging Face 帳號及 API Token（用於 `InferenceClientModel`） | |
| ### 本地執行 | |
| ```bash | |
| # 1. Clone 專案 | |
| git clone https://huggingface.co/spaces/<your-username>/AgenticRAG | |
| cd AgenticRAG | |
| # 2. 建立虛擬環境 | |
| python -m venv .venv | |
| source .venv/bin/activate # Windows: .venv\Scripts\activate | |
| # 3. 安裝依賴 | |
| pip install -r requirements.txt | |
| # 4. 設定 Hugging Face Token | |
| export HF_TOKEN=your_token_here # Windows: set HF_TOKEN=your_token_here | |
| # 5. 啟動應用程式 | |
| python app.py | |
| ``` | |
| 啟動後瀏覽器將自動開啟 Gradio 介面（預設 `http://localhost:7860`）。 | |
| ### 部署到 Hugging Face Spaces | |
| 本專案已配置 HF Spaces 所需的 YAML frontmatter（位於 `README.md` 頂部）， | |
| 只需 push 至對應的 Space 倉庫即可自動部署。 | |
| --- | |
| ## 🔑 環境變數 | |
| | 變數名稱 | 說明 | 必填 | | |
| |---|---|---| | |
| | `HF_TOKEN` | Hugging Face API Token，用於呼叫推論 API 及存取資料集 | ✅ | | |
| --- | |
| ## 💬 使用範例 | |
| 在 Gradio 聊天介面中，你可以嘗試以下問題： | |
| | 問題範例 | 使用的工具 | | |
| |---|---| | |
| | `Who is Lady Whiskers?` | 🎭 Guest Info Retriever | | |
| | `What's the weather like in Paris?` | 🌤 Weather Info | | |
| | `What is the most downloaded model by meta-llama?` | 📊 Hub Stats | | |
| | `What is the latest news about AI?` | 🔍 DuckDuckGo Search | | |
| | `Find info about Dr. Adventures and check the weather in his city` | 🎭 + 🌤 （多工具組合） | | |
| --- | |
| ## 🛠 技術棧 | |
| | 技術 | 用途 | | |
| |---|---| | |
| | [smolagents](https://github.com/huggingface/smolagents) | Agent 框架（CodeAgent + Tool 抽象層） | | |
| | [Qwen2.5-Coder-32B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct) | 底層大語言模型（透過 HF Inference API） | | |
| | [Gradio](https://gradio.app/) | Web UI 框架 | | |
| | [LangChain Community](https://python.langchain.com/) | BM25Retriever 檢索器 | | |
| | [Hugging Face Datasets](https://huggingface.co/docs/datasets) | 賓客資料集載入 | | |
| | [Hugging Face Hub](https://huggingface.co/docs/huggingface_hub) | 模型統計查詢 API | | |
| | [DuckDuckGo Search](https://pypi.org/project/duckduckgo-search/) | 網頁搜尋引擎 | | |
| --- | |
| ## 📄 授權條款 | |
| 本專案採用 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 授權。 |