Skip to main content

Kiến trúc Synapse

intermediate 🤖 Thân thiện với LLM 3 phút · 572 từ Cập nhật: 2026-06-27 Tiếng Việt

Cách Synapse được xây dựng — Fastify, PostgreSQL, FTS5, embeddings, MCP server.

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM
Ngôn ngữ: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Kiến trúc Synapse

Synapse là API bộ nhớ multi-tenant được xây dựng trên Fastify, PostgreSQL với FTS5, và một dịch vụ embeddings tùy chọn cho tìm kiếm ngữ nghĩa.

Kiến trúc tổng quan

┌──────────────────────────────────────────────────────────┐
│                       Clients                            │
├──────────────┬──────────────┬──────────────┬─────────────┤
│  LLM Agents  │  Web Browsers│  MCP Clients │  Webhooks   │
│  (curl/SDK)  │  (humans)    │ (Claude/etc) │  (external) │
└──────┬───────┴──────┬───────┴──────┬───────┴──────┬──────┘
       │              │              │              │
       └──────────────┴──────────────┴──────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │    Synapse API (Fastify)      │
              │    port 12800                 │
              │    - REST endpoints           │
              │    - Auth (Mind Key / JWT)    │
              │    - Rate limiting            │
              │    - Static file serving      │
              └───────────────┬───────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
       ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
       │ PostgreSQL  │ │ Embeddings  │ │ MCP Server  │
       │ + FTS5      │ │ Service     │ │ (separate)  │
       │             │ │ (optional)  │ │ port 13100  │
       │ - memories  │ │             │ │             │
       │ - tasks     │ │ - generate  │ │ - 79 tools  │
       │ - chat      │ │   embeddings│ │ - stdio/SSE │
       │ - scripts   │ │             │ │ - WebSocket │
       └─────────────┘ └─────────────┘ └─────────────┘

Thành phần cốt lõi

1. Synapse API (Fastify)

HTTP server chính. Xử lý:

  • Endpoint REST (/memory, /chat, /mind/tasks, v.v.)
  • Xác thực (Mind Key cho agent, JWT cho con người)
  • Giới hạn tốc độ (chỉ xác thực ?key=)
  • Phục vụ tệp tĩnh (giao diện web tại /human, /docs, v.v.)
  • Phân phối webhook

Được xây dựng với Fastify 5 cho hiệu suất. Chạy trên cổng 12800 trong môi trường production.

2. PostgreSQL với FTS5

Kho dữ liệu chính. Sử dụng PostgreSQL với phần mở rộng FTS5 cho tìm kiếm toàn văn.

Bảng chính:

Bảng Mục đích
users Tài khoản người dùng
minds Phạm vi mind (mỗi cái có một Mind Key)
memories Bản ghi bộ nhớ với bảng ảo FTS5
tasks Quản lý tác vụ
chat_messages Lịch sử chat
scripts Script cố định
webhooks Đăng ký webhook
cron_jobs Tác vụ đã lên lịch
variables Cửa hàng key-value
audit_log Nhật ký kiểm toán

FTS5 cho phép tìm kiếm toàn văn dưới mili giây trên toàn bộ nội dung bộ nhớ. Xem Tìm kiếm FTS5 để biết chi tiết.

3. Dịch vụ Embeddings (Tùy chọn)

Đối với tìm kiếm ngữ nghĩa, Synapse tạo vector embeddings của nội dung bộ nhớ. Chúng được lưu cùng với bộ nhớ và dùng cho tìm kiếm tương tự.

  • Provider: có thể cấu hình (OpenAI, mô hình cục bộ, v.v.)
  • Lưu dưới dạng cột vector trong bảng memories
  • Được sử dụng bởi endpoint /memory/semantic-search
  • Xem Tìm kiếm ngữ nghĩa

4. MCP Server (Dịch vụ riêng)

Synapse MCP server chạy như một tiến trình riêng (cổng 13100). Nó:

  • Cung cấp 79 công cụ qua Model Context Protocol
  • Hỗ trợ transport stdio, HTTP/SSE và WebSocket
  • Dịch các lệnh gọi công cụ MCP thành lệnh gọi Synapse API
  • Multi-tenant: một Mind Key mỗi phiên

5. Browser Proxy (Dịch vụ riêng)

Đối với tự động hóa trình duyệt, một dịch vụ riêng dựa trên Playwright chạy trên cổng 13000. MCP server có thể gọi dịch vụ này cho các công cụ browser_*.

6. SSH Proxy (Dịch vụ riêng)

Đối với lệnh từ xa dựa trên SSH, một dịch vụ riêng chạy trên cổng 12900.

Mô hình Multi-Tenancy

User Account (email + password)
  │
  ├── Mind 1 (Mind Key 1)
  │   ├── Memories
  │   ├── Tasks
  │   ├── Chat
  │   └── Scripts
  │
  ├── Mind 2 (Mind Key 2)
  │   └── ... (isolated from Mind 1)
  │
  └── Mind 3 (Mind Key 3)
      └── ...

Mỗi mind hoàn toàn tách biệt. Mind Key cấp quyền truy cập chính xác một mind. JWT cấp quyền truy cập tài khoản người dùng (để quản lý mind).

Xem Multi-Tenancy để biết chi tiết.

Luồng yêu cầu

Yêu cầu lưu bộ nhớ

1. Client sends POST /memory with Authorization: Bearer mk_xxx
2. Fastify receives request
3. Auth middleware validates Mind Key, attaches mind_id to request
4. Memory route handler:
   a. Validate JSON body (zod schema)
   b. Insert into memories table
   c. Update FTS5 index
   d. (Async) Generate embedding if embeddings enabled
   e. Trigger webhooks for memory.store event
5. Return { id, status: "stored" }

Yêu cầu tìm kiếm bộ nhớ

1. Client sends GET /memory/search?q=docker
2. Auth middleware validates Mind Key
3. Memory route handler:
   a. Parse query (FTS5 syntax)
   b. Execute FTS5 MATCH against memories table
   c. Filter by mind_id (tenant isolation)
   d. Rank by relevance
   e. Return results

Triển khai

Synapse được triển khai dưới dạng Docker container. Xem docker-compose.yml:

services:
  synapse:
    image: registry.gitlab.com/schaefer-services/synapse:latest
    ports:
      - "12800:12800"
    environment:
      - DATABASE_URL=postgres://...
      - JWT_SECRET=...
      - SYNAPSE_HOST=0.0.0.0
      - SYNAPSE_PORT=12800
    depends_on:
      - postgres
  
  postgres:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=synapse
      - POSTGRES_PASSWORD=...

Đặc tính hiệu suất

Thao tác Độ trễ Thông lượng
Lưu bộ nhớ ~5ms 1000+ req/s
Thu hồi bộ nhớ ~20ms 500 req/s
Tìm kiếm FTS5 ~10ms 800 req/s
Tìm kiếm ngữ nghĩa ~50ms 200 req/s
Poll chat ~5ms 2000 req/s

Bước tiếp theo

← Quay lại Khái niệm