Unit_3_Agentic_RAG

Sleeping

App Files Files Community

Unit_3_Agentic_RAG / README.md

solnone

docs: update README documentation and add missing dependencies

c3fcddc about 1 month ago

preview code

Raw History Blame Contribute Delete

7.51 kB

A newer version of the Gradio SDK is available: 6.30.0

Upgrade

metadata

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，透過 Gradio 提供互動式 Web UI。

🧠 專案簡介

本專案是 Hugging Face 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
類別：GuestInfoRetrieverTool
說明：從 Hugging Face Datasets（agents-course/unit3-invitees）載入賓客資料，
使用 BM25 演算法 進行關鍵字檢索，回傳最相關的前 3 筆賓客資訊。
輸入：賓客姓名或關係（query: str）
輸出：包含姓名、關係、描述、Email 的文字資訊

2. 🌤 天氣查詢 (`weather_info`)

檔案：tools.py
類別：WeatherInfoTool
說明：根據指定地點回傳模擬天氣資料（Rainy / Clear / Windy + 溫度）。
目前為 Demo 用途，使用隨機產生的假資料。
輸入：地點名稱（location: str）
輸出：天氣狀況與溫度字串

3. 📊 Hub 模型統計 (`hub_stats`)

檔案：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）

本地執行

# 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	Agent 框架（CodeAgent + Tool 抽象層）
Qwen2.5-Coder-32B-Instruct	底層大語言模型（透過 HF Inference API）
Gradio	Web UI 框架
LangChain Community	BM25Retriever 檢索器
Hugging Face Datasets	賓客資料集載入
Hugging Face Hub	模型統計查詢 API
DuckDuckGo Search	網頁搜尋引擎

📄 授權條款

本專案採用 Apache License 2.0 授權。