PRD.md

PRD（v0.1）— RAG Agent Ops Console（內部版）

0) 目標與邊界

目的

提供一個內部後台，讓非技術人員可「上架與測試」RAG Agent：

• Agent CRUD（含版本/發佈）
• Upload file → 抽取/切片/嵌入/入庫
• File search（跨文件關鍵字/語意檢索）
• Pipeline 可視化（可重跑/追蹤狀態）
• Vector store（文件/集合/向量）清單與 CRUD
• RAG Agent Prompt 設定 & 測試互動（顯示引用）

當前邊界

不做 Login/User、多租戶；僅內網/私有環境使用。

技術棧

• 後端: FastAPI（後端與後台頁面）
• AI: OpenAI API（回覆/嵌入，先用官方 embedding；之後可換自建）
• 資料庫: Postgres(+pgvector) 儲存
• 儲存: 物件儲存（可用本地或 Supabase Storage）

1) 使用者角色（內部）

Operator（營運/編輯）

上傳檔案、管理集合、調整 Prompt、測試 Agent。

Admin（技術/維運）

管理 Agent 版本、重跑 Pipeline、檢視日誌。

無登入版

以 Admin-Key 或內網 ACL 限制。

2) 成功指標（MVP）

1. 10 分鐘內可完成: 建立一個 Agent → 上傳 PDF → 索引完成 → 在測試台得到帶引用的回覆
2. 檔案處理失敗率 < 5%；失敗皆有可讀錯誤與可重跑
3. 檢索延遲（Top-K=5）< 300ms（不含生成）

3) 頁面與流程（內嵌於 FastAPI 的 Console）

路徑：/console/*（內部可見即可）

Agents

• 清單（名稱、狀態、當前版本、最後更新）
• 建立/編輯（Name、Description、Slug）
• 版本列表（draft/published、建立時間）
• 新增版本（從現行版複製為 draft）/ 發佈 / 回滾（切換 active）

Upload

• 拖拉 PDF（多檔）/ 輸入 URL / 貼純文字
• 送出後顯示Pipeline 執行卡：抽取 → 切片 → 嵌入 → 入庫
• 完成後顯示：文件標題、頁數、chunk 數、大小

Documents / Collections

• 文件清單（標題、來源、大小、頁數、更新時間、所屬集合）
• 動作: 加入/移出集合、重嵌入、刪除
• 集合清單: 建立/改名/刪除；顯示文件數、總向量數

File Search

• Query 欄（關鍵字 + 語意）
• 過濾: 集合、日期、來源
• 結果: snippet、文件/頁碼、score、打開原文片段

Pipelines

• 每次上傳或重嵌入對應一個 Pipeline Run
• 狀態流: QUEUED → EXTRACTING → CHUNKING → EMBEDDING → INDEXED → DONE / FAILED
• 可重跑/續跑，展開查看錯誤與原始日誌

Prompts / Test Bench

• Active System Prompt 顯示與編輯（產生新版本，草稿狀態）
• Agent Config: 模型、溫度、Top-K、引用必須、Hybrid 檢索開關
• 測試台: 輸入問題 → 串流顯示答案 + 引用卡片（文件/頁碼/片段）

4) User Stories（含驗收準則）

US-A1 建立 Agent（CRUD）

Given 我在 Agents 頁 When 我點「Create」，輸入 name/description Then 會建立 agents 一筆（status=draft），並自動產生 agent_versions(version=1, state=draft, config=預設) AC: 建立後可在列表看到該 Agent；可進入詳情查看版本=1 的草稿

US-A2 版本發佈 / 回滾

When 我在該 Agent 的版本列表選擇某 draft，點「Publish」 Then 該版本 state → published，並設為 active_version_id AC: Agents 清單顯示 active 版本；測試台預設使用 active 版本

US-U1 上傳 PDF 並索引

Given 我在 Upload 頁 When 我拖拉 1~n 個 PDF 上傳 Then 後端啟動 Pipeline，逐步顯示狀態；完成後文件出現在 Documents AC: 每個檔案有完成或失敗狀態；失敗可重試；完成顯示頁數/大小/chunk 數

US-S1 File Search（跨文件）

When 我輸入關鍵字或問題並搜尋 Then 回傳匹配的 chunk 清單（snippet+來源+score）；可點擊開啟來源預覽 AC: 可用集合/日期過濾；結果 1 秒內返回（不含生成）

US-P1 Pipeline 可視化

When 我查看特定文件的 Pipeline Run Then 能看到每階段狀態、耗時、錯誤訊息；可點「重跑」 AC: Run 狀態可從失敗變成功（處理暫時錯誤）

US-V1 Vector Store CRUD（集合/文件/向量）

When 我在 Collections 頁建立/刪除集合、移入/移出文件 Then 文件與集合的關聯變更；檢索範圍亦更新 AC: 集合頁顯示文件數與總向量數；刪除集合不刪文件

US-R1 設定 Prompt 與測試互動

When 我在 Prompts 頁修改 System Prompt（產生新版本草稿）並在 Test Bench 啟動測試 Then 以該草稿配置回覆並顯示引用；按「Publish」才會成為 active AC: 回覆包含 ≥1 個引用；若無引用且 require_citations=true，則回覆應提示找不到可引用來源

5) 資料模型（精簡）

Agents

agents(
  id,
  slug,
  name,
  description,
  status,
  active_version_id,
  created_at,
  updated_at
)

agent_versions(
  id,
  agent_id,
  version,
  state,
  config_json,
  created_at,
  created_by
)

Knowledge & Vectors

datasources(
  id,
  type,  -- [pdf|url|text]
  source_uri,
  created_at
)

documents(
  id,
  datasource_id,
  title,
  bytes,
  pages,
  meta_json,
  updated_at
)

chunks(
  id,
  doc_id,
  ordinal,
  text,
  meta_json
)

embeddings(
  id,
  chunk_id,
  embedding vector(1536 or 3072)  -- 先用 OpenAI embeddings 維度
)

collections(
  id,
  name,
  created_at
)

collection_items(
  collection_id,
  doc_id,
  created_at
)

Pipelines / Logs

pipeline_runs(
  id,
  scope,  -- [ingest|reembed]
  target_id,
  status,
  steps_json,
  started_at,
  ended_at,
  error_msg
)

chat_logs(
  id,
  agent_id,
  version_id,
  question,
  answer,
  citations_json,
  tokens_in,
  tokens_out,
  latency_ms,
  created_at
)

6) API（後端 FastAPI，無登入版）

Agents

• GET /api/agents?status=&q=&page=&page_size=
• POST /api/agents（name, description, slug）
• GET /api/agents/{agent_id}
• PATCH /api/agents/{agent_id}（name/description/slug/status）
• DELETE /api/agents/{agent_id}（軟刪或硬刪）
• GET /api/agents/{agent_id}/versions
• POST /api/agents/{agent_id}/versions（clone active 為 draft，可附 override）
• GET /api/agents/{agent_id}/versions/{version_id}
• PATCH /api/agents/{agent_id}/versions/{version_id}（只允許 draft 改 config_json 子欄位）
• POST /api/agents/{agent_id}/versions/{version_id}/publish

Upload / Ingest / Pipelines

• POST /api/ingest/files（multipart 多檔）
• POST /api/ingest/url
• POST /api/ingest/text
• GET /api/pipelines/runs?target_id=
• GET /api/pipelines/runs/{run_id}
• POST /api/pipelines/runs/{run_id}/retry

Documents / Collections / Search

• GET /api/documents?collection_id=&q=&page=
• POST /api/documents/{doc_id}/reembed
• DELETE /api/documents/{doc_id}
• GET /api/collections
• POST /api/collections
• DELETE /api/collections/{id}
• POST /api/collections/{id}/add（doc_id[]）
• POST /api/collections/{id}/remove
• POST /api/search → {query, top_k, filters?} → hits:[{doc_id, chunk_id, text, score, meta}]

Prompts / Test Bench

• GET /api/agents/{agent_id}/active-config（合併後的有效 config）
• POST /api/test/run → {agent_id, version_id?, question, top_k?, collection_id?} → 流式/非流式回答 + citations[]

7) Pipeline 定義（可視化對應）

Steps

（至少包含以下名稱，前端以此畫進度條）：

• EXTRACT_TEXT → CHUNK → EMBED → UPSERT_VECTORS → DONE（或 FAILED）

steps_json

每步：{name, status, started_at, ended_at, metrics, error?}

8) 非功能需求

穩定性

單檔 30MB PDF 可在 3 分鐘內完成入庫（取決於抽取/嵌入速率）。

可觀測

每個 Run/Chat 都有可追蹤 ID 與原始錯誤。

安全（無登入版）

• 預設只對內網開放；或要求 x-admin-key
• 物件儲存限制為私有桶；僅後端可讀

9) 風險與緩解

抽取品質不一（掃描 PDF）

加入失敗清單與「重新 OCR」選項（之後擴充）。

成本不可控（OpenAI 嵌入/生成）

• 嵌入去重（hash）、相同內容不重算
• 問答限制最大上下文/輪數；快取檢索結果

引用不充分

預設 require_citations=true，否則降低置信/請求澄清。

10) 里程碑（按功能順序）

1. Agent CRUD + 版本發佈（/agents, /versions）
2. Upload & Ingest + Pipeline 可視化（/ingest, /pipelines）
3. Documents/Collections + Search（清單/檢索/CRUD）
4. Vector Store CRUD（重嵌入、刪除、集合管理與指標）
5. Prompts + Test Bench（草稿測試 → 發佈）
6. （可選）簡報表/日誌匯出（成本、延遲、引用率）

備註

• 目前嵌入先用 OpenAI embeddings（維度 1536+），方便上線；未來可替換：Hugging Face TEI / bge 系列 → 只需替換 EMBED_PROVIDER 介面，不動資料表。
• 前端頁面由 FastAPI 內嵌簡單模板（或極薄 React），等需要產品化再抽離到 Next.js，API 契約不變。