apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-04-27 09:46:25 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
SurfSense/_bmad-output/connectors-explained.md

11 KiB
Raw Blame History

Giải Thích Hệ Thống Connectors

Tài liệu bổ sung cho SurfSense

📌 Connectors Là Gì?

Connectors (Bộ kết nối) là tính năng cho phép SurfSense tìm kiếm và truy xuất dữ liệu từ các ứng dụng bên ngoài mà bạn đang sử dụng hàng ngày, như:

  • 📧 Gmail - Tìm kiếm trong emails
  • 📁 Google Drive - Tìm kiếm files và documents
  • 📅 Google Calendar - Tìm kiếm events và meetings
  • 💬 Slack - Tìm kiếm messages và conversations
  • 📝 Notion - Tìm kiếm pages và databases
  • 🎯 Linear - Tìm kiếm issues và projects
  • 📊 Airtable - Tìm kiếm bases và records
  • 🎫 Jira - Tìm kiếm tickets
  • 📚 Confluence - Tìm kiếm wiki pages
  • 🗂️ Microsoft Teams - Tìm kiếm chats và files

Tổng cộng: SurfSense hỗ trợ 26+ connectors khác nhau!

🎯 Mục Đích

Thay vì phải:

  1. Mở Gmail → tìm kiếm email
  2. Mở Google Drive → tìm kiếm file
  3. Mở Slack → tìm kiếm message
  4. Mở Notion → tìm kiếm note

Bạn chỉ cần:

  • Mở SurfSense → Tìm kiếm 1 lần → Nhận kết quả từ TẤT CẢ các ứng dụng đã kết nối!

🔌 Cách Hoạt Động

Bước 1: Kết Nối (Connect)

Khi bạn click nút "Connect" bên cạnh một connector (ví dụ: Google Drive):

  1. OAuth Authentication:

    • SurfSense chuyển hướng bạn đến trang đăng nhập của Google
    • Bạn đăng nhập và cấp quyền cho SurfSense:
      • ✅ Đọc files trong Drive
      • ✅ Đọc metadata (tên file, ngày tạo, etc.)
      • ❌ KHÔNG có quyền xóa hoặc chỉnh sửa files

  2. Lưu Access Token:

    • Google trả về một access token (mã truy cập)
    • SurfSense lưu token này vào database (được mã hóa)
    • Token này cho phép SurfSense truy cập Drive của bạn thay mặt bạn

  3. Tạo Connector Record:

    • SurfSense tạo 1 record trong bảng search_source_connectors: 
      {
  "id": 123,
  "name": "My Google Drive",
  "connector_type": "GOOGLE_DRIVE_CONNECTOR",
  "user_id": "your-user-id",
  "search_space_id": 1,
  "config": {
    "access_token": "encrypted_token",
    "refresh_token": "encrypted_refresh_token"
  },
  "is_indexable": true,
  "periodic_indexing_enabled": true,
  "indexing_frequency_minutes": 60
}

Bước 2: Indexing (Lập Chỉ Mục)

Sau khi kết nối thành công, SurfSense bắt đầu indexing (lập chỉ mục) dữ liệu:

  1. Fetch Data từ API:

    • SurfSense gọi API của Google Drive (sử dụng access token)
    • Lấy danh sách tất cả files: GET https://www.googleapis.com/drive/v3/files
    • Với mỗi file, lấy:
      • Tên file
      • Nội dung (text content)
      • Metadata (owner, created_at, modified_at, etc.)

  2. Tạo Embeddings:

    • Nội dung file được chuyển thành vector embeddings (dùng OpenAI/Gemini)
    • Ví dụ: File "Project Plan.docx" → Vector 1536 chiều
    • Vector này biểu diễn ý nghĩa ngữ nghĩa của nội dung

  3. Lưu vào Database:

    • PostgreSQL (bảng documents):

      INSERT INTO documents (
  title, content, document_type, source_connector_id, user_id
) VALUES (
  'Project Plan.docx',
  'Full text content...',
  'GOOGLE_DRIVE_FILE',
  123,  -- connector_id
  'your-user-id'
);

    • Vector Database (Qdrant):

      {
  "id": "doc-456",
  "vector": [0.123, -0.456, 0.789, ...],  // 1536 dimensions
  "payload": {
    "title": "Project Plan.docx",
    "document_id": 456,
    "connector_type": "GOOGLE_DRIVE_FILE"
  }
}

  4. Periodic Re-indexing:

    • Mỗi 60 phút (hoặc theo cấu hình), SurfSense tự động:
      • Kiểm tra files mới
      • Kiểm tra files đã update
      • Re-index nếu có thay đổi

Bước 3: Search (Tìm Kiếm)

Khi bạn tìm kiếm trong SurfSense:

  1. User Query:

    • Bạn nhập: "project timeline for Q1"

  2. Query Embedding:

    • SurfSense chuyển query thành vector: [0.234, -0.567, ...]

  3. Vector Search:

    • Tìm kiếm trong Qdrant (similarity search): 
      results = qdrant_client.search(
  collection_name="surfsense",
  query_vector=[0.234, -0.567, ...],
  limit=10,
  filter={
    "user_id": "your-user-id",
    "connector_type": ["GOOGLE_DRIVE_FILE", "GMAIL", "NOTION"]
  }
)

  4. Kết Quả:

    • Trả về top 10 documents có vector gần nhất (most similar)
    • Ví dụ: 
      1. "Q1 Project Timeline.xlsx" (Google Drive) - 95% match
2. "Email: Q1 Planning Meeting" (Gmail) - 87% match
3. "Notion: Q1 Roadmap" (Notion) - 82% match

  5. AI Chat (Optional):

    • Nếu bạn dùng AI Chat, SurfSense sẽ:
      • Lấy nội dung của top 10 results
      • Gửi cho LLM (GPT-4/Claude/Gemini) kèm theo query
      • LLM tổng hợp và trả lời câu hỏi dựa trên context

🔐 Bảo Mật

Quyền Truy Cập

  • Read-only: Connectors chỉ có quyền ĐỌC, không thể xóa/sửa dữ liệu
  • User-scoped: Mỗi user chỉ thấy dữ liệu của chính họ
  • Encrypted: Access tokens được mã hóa trong database

Revoke Access (Thu Hồi Quyền)

Bạn có thể ngắt kết nối bất cứ lúc nào:

  1. Trong SurfSense:

    • Vào Settings → Connectors
    • Click "Disconnect" bên cạnh connector
    • SurfSense sẽ:
      • Xóa access token
      • Xóa tất cả indexed data từ connector đó

  2. Trong Google/Slack/etc:

📊 Loại Connectors

1. Managed OAuth (Composio)

Ví dụ: Google Drive, Gmail, Google Calendar

  • Sử dụng Composio (third-party OAuth provider)
  • Ưu điểm:
    • Setup nhanh (không cần tạo OAuth app riêng)
    • Composio quản lý token refresh tự động
  • Nhược điểm:
    • Phụ thuộc vào Composio service

Flow:

User → SurfSense → Composio → Google OAuth → Access Token → SurfSense

2. Quick Connect (Direct OAuth)

Ví dụ: Notion, Slack, Linear, Airtable

  • Kết nối trực tiếp với API của ứng dụng
  • Ưu điểm:
    • Không phụ thuộc third-party
    • Full control
  • Nhược điểm:
    • Cần setup OAuth app riêng cho mỗi service

Flow:

User → SurfSense → Notion OAuth → Access Token → SurfSense

3. API Key Based

Ví dụ: Elasticsearch, Webcrawler

  • Không dùng OAuth, chỉ cần API key
  • User nhập API key trực tiếp vào SurfSense

4. Self-Hosted Only

Ví dụ: Obsidian Connector

  • Chỉ hoạt động khi SurfSense chạy self-hosted
  • Truy cập trực tiếp vào local file system

🛠️ Cấu Hình Connector

Mỗi connector có các settings:

Indexing Settings

{
  "periodic_indexing_enabled": true,
  "indexing_frequency_minutes": 60,
  "next_scheduled_at": "2026-01-31T15:00:00Z"
}
  • periodic_indexing_enabled: Bật/tắt auto re-index
  • indexing_frequency_minutes: Tần suất re-index (phút)
  • next_scheduled_at: Lần re-index tiếp theo

Connector-Specific Config

Google Drive:

{
  "folders": ["folder-id-1", "folder-id-2"],  // Chỉ index các folders này
  "file_types": ["document", "spreadsheet"],  // Chỉ index loại files này
  "exclude_shared": false  // Index cả shared files
}

Slack:

{
  "channels": ["general", "engineering"],  // Chỉ index các channels này
  "include_dms": true,  // Index direct messages
  "date_range_days": 90  // Chỉ index 90 ngày gần nhất
}

💡 Use Cases

1. Knowledge Worker

Scenario: Bạn là Product Manager, cần tìm thông tin về feature request từ khách hàng.

Trước khi có Connectors:

  • Tìm trong Gmail → Không thấy
  • Tìm trong Slack → Không thấy
  • Tìm trong Notion → Không thấy
  • Tìm trong Linear → Tìm thấy!
  • Tổng thời gian: 15 phút

Sau khi có Connectors:

  • Mở SurfSense → Tìm kiếm: "customer feature request payment"
  • Kết quả:
    1. Linear Issue #123
    2. Slack message từ customer
    3. Email thread với customer
    4. Notion doc: Feature Spec
  • Tổng thời gian: 30 giây

2. Developer

Scenario: Debug lỗi production, cần tìm code changes liên quan.

Connectors kết nối:

  • GitHub (code commits)
  • Slack (engineering channel)
  • Jira (bug tickets)
  • Confluence (technical docs)

Search query: "payment API timeout error"

Kết quả:

  1. GitHub commit: "Fix payment timeout"
  2. Jira ticket: PROD-456
  3. Slack discussion về issue
  4. Confluence: Payment API Architecture

🚨 Lưu Ý Quan Trọng

1. Research Mode KHÔNG Tồn Tại Trên FE

Sự thật:

  • Tài liệu trước đó (user-guide.md) đề cập "Research Mode" là SAI
  • Frontend chỉ có 1 chế độ chat duy nhất
  • Backend có thể có logic khác nhau, nhưng user không thấy toggle nào

Đã sửa: Tài liệu sẽ được cập nhật để loại bỏ phần Research Mode.

2. Connector ≠ Extension

  • Browser Extension: Capture nội dung từ trang web bạn đang browse
  • Connectors: Fetch dữ liệu từ các ứng dụng bên ngoài (Gmail, Drive, etc.)
  • Hai tính năng độc lập nhưng bổ sung cho nhau

3. Privacy

  • Dữ liệu được index chỉ dành cho bạn
  • Không ai khác (kể cả admin) có thể thấy nội dung files của bạn
  • Trừ khi bạn share chat với visibility = "SEARCH_SPACE"

📞 Troubleshooting

Connector Không Hoạt Động

Triệu chứng: Sau khi connect, không thấy kết quả khi search.

Kiểm tra:

  1. Indexing status:

    SELECT name, connector_type, last_indexed_at, next_scheduled_at
FROM search_source_connectors
WHERE user_id = 'your-user-id';
    • Nếu last_indexed_at = NULL → Indexing chưa chạy

  2. Backend logs:

    grep "connector" surfsense_backend/logs/app.log
    • Tìm lỗi liên quan đến connector

  3. Token expired:

    • Access token có thể hết hạn
    • Disconnect và reconnect lại connector

Kết Quả Không Chính Xác

Nguyên nhân:

  • Embeddings không capture đúng ý nghĩa
  • Cần re-index với model tốt hơn

Giải pháp:

  • Admin có thể trigger manual re-index: 
    python manage.py reindex-connector --connector-id 123

Cập nhật: 2026-01-31 | Version: 1.0