README.md

---
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) 授權。