Supabase 2026: Giải pháp thay thế Firebase mã nguồn mở với Postgres Vector Search cho 1M+ ứng dụng AI — Hướng dẫn cài đặt

# Dự án của bạn đi kèm với:
# - Cơ sở dữ liệu PostgreSQL 16
# - API REST tự động tạo
# - Xác thực tích hợp
# - 500 MB lưu trữ cơ sở dữ liệu (tier miễn phí)
# - 1 GB lưu trữ file (tier miễn phí)
# - 2 GB băng thông (tier miễn phí)

# Cài đặt Supabase CLI
# macOS
brew install supabase/tap/supabase

# Linux
npm install -g supabase

# Xác minh cài đặt
supabase --version
# Kỳ vọng: 1.220.0

# Đăng nhập tài khoản
supabase login

# Khởi tạo dự án mới
mkdir my-ai-app && cd my-ai-app
supabase init

# Khởi động stack cục bộ (Docker bắt buộc)
supabase start

# Output bao gồm URL API cục bộ, anon key, và service role key
# API URL: http://localhost:54321
# GraphQL URL: http://localhost:54321/graphql/v1
# anon key: eyJhbGciOiJIUzI1NiIs...

# Clone repository tự host chính thức
git clone https://github.com/supabase/supabase.git
cd supabase/docker

# Sao chép và chỉnh sửa biến môi trường
cp .env.example .env

# Tạo khóa bảo mật
openssl rand -base64 32  # Cho JWT secret
openssl rand -hex 32     # Cho anon/service keys

# Chỉnh sửa .env với domain, cài đặt SMTP, và thông tin xác thực S3
nano .env

# Khởi động stack
docker compose up -d

# Xác minh tất cả dịch vụ đều khỏe mạnh
docker compose ps

# Output kỳ vọng:
# NAME                STATUS
# supabase-db         healthy
# supabase-kong       healthy
# supabase-auth       healthy
# supabase-rest       healthy
# supabase-realtime   healthy
# supabase-storage    healthy
# supabase-meta       healthy
# supabase-studio     healthy

# Cài đặt thư viện client
npm install @supabase/supabase-js

# Hoặc cho Python
pip install supabase

// TypeScript / Next.js
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

// Test kết nối
const { data, error } = await supabase.from('test').select('*')
console.log(data)

# Python
from supabase import create_client

supabase = create_client(
    "https://your-project.supabase.co",
    "your-anon-key"
)

# Test kết nối
response = supabase.table('test').select('*').execute()
print(response.data)

-- Trong Trình soạn thảo SQL Supabase hoặc psql
CREATE EXTENSION IF NOT EXISTS vector;

-- Xác minh tiện ích mở rộng đã được cài đặt
SELECT * FROM pg_extension WHERE extname = 'vector';

-- Tạo bảng tài liệu với embedding
CREATE TABLE documents (
    id          BIGSERIAL PRIMARY KEY,
    title       TEXT NOT NULL,
    content     TEXT NOT NULL,
    source_url  TEXT,
    embedding   VECTOR(1536),  -- Khớp với OpenAI text-embedding-3-large
    metadata    JSONB DEFAULT '{}',
    created_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Tạo chỉ mục HNSW cho tìm kiếm tương đồng nhanh
CREATE INDEX idx_documents_embedding
ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- Thêm chỉ mục tìm kiếm toàn văn cho tìm kiếm hybrid
CREATE INDEX idx_documents_fts ON documents
USING GIN (to_tsvector('english', content));

# Python: Tạo embedding và chèn vào Supabase
from supabase import create_client
import openai

supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
client = openai.OpenAI(api_key=OPENAI_API_KEY)

def insert_document(title: str, content: str, source_url: str = None):
    # Tạo embedding
    response = client.embeddings.create(
        input=content,
        model="text-embedding-3-large"
    )
    embedding = response.data[0].embedding

    # Chèn vào Supabase
    result = supabase.table('documents').insert({
        'title': title,
        'content': content,
        'source_url': source_url,
        'embedding': embedding,
        'metadata': {'word_count': len(content.split())}
    }).execute()
    return result

# Chèn tài liệu mẫu
insert_document(
    title="Docker Best Practices 2026",
    content="Use multi-stage builds to reduce image size...",
    source_url="https://docs.docker.com"
)

-- SQL thuần: Tìm 5 tài liệu tương đồng nhất
SELECT
    id,
    title,
    content,
    1 - (embedding <=> :query_embedding::vector) AS similarity
FROM documents
ORDER BY embedding <=> :query_embedding::vector
LIMIT 5;

# Python: Hàm truy xuất RAG
async def search_similar_documents(query: str, top_k: int = 5):
    # Tạo query embedding
    response = client.embeddings.create(
        input=query,
        model="text-embedding-3-large"
    )
    query_embedding = response.data[0].embedding

    # Truy vấn Supabase
    result = await supabase.rpc(
        'match_documents',
        {
            'query_embedding': query_embedding,
            'match_threshold': 0.7,
            'match_count': top_k
        }
    ).execute()
    return result.data

-- Tạo thủ tục lưu trữ cho việc truy xuất tài liệu
CREATE OR REPLACE FUNCTION match_documents(
    query_embedding VECTOR(1536),
    match_threshold FLOAT,
    match_count INT
)
RETURNS TABLE (
    id BIGINT,
    title TEXT,
    content TEXT,
    similarity FLOAT
)
LANGUAGE plpgsql
AS $$
BEGIN
    RETURN QUERY
    SELECT
        d.id,
        d.title,
        d.content,
        1 - (d.embedding <=> query_embedding) AS similarity
    FROM documents d
    WHERE 1 - (d.embedding <=> query_embedding) > match_threshold
    ORDER BY d.embedding <=> query_embedding
    LIMIT match_count;
END;
$$;

# rag_pipeline.py
from supabase import create_client
from openai import OpenAI
import json

class SupabaseRAG:
    def __init__(self, supabase_url: str, supabase_key: str, openai_key: str):
        self.supabase = create_client(supabase_url, supabase_key)
        self.openai = OpenAI(api_key=openai_key)

    def embed_and_store(self, chunks: list[dict]):
        """Lưu trữ các chunk tài liệu với embedding."""
        for chunk in chunks:
            embedding = self.openai.embeddings.create(
                input=chunk['text'],
                model="text-embedding-3-large"
            ).data[0].embedding

            self.supabase.table('documents').insert({
                'title': chunk['title'],
                'content': chunk['text'],
                'embedding': embedding,
                'metadata': chunk.get('metadata', {})
            }).execute()

    def retrieve(self, query: str, top_k: int = 5) -> list[dict]:
        """Truy xuất tài liệu liên quan sử dụng tìm kiếm vector."""
        query_embedding = self.openai.embeddings.create(
            input=query,
            model="text-embedding-3-large"
        ).data[0].embedding

        results = self.supabase.rpc(
            'match_documents',
            {
                'query_embedding': query_embedding,
                'match_threshold': 0.75,
                'match_count': top_k
            }
        ).execute()
        return results.data

    def generate(self, query: str, context: list[dict]) -> str:
        """Tạo phản hồi sử dụng ngữ cảnh đã truy xuất."""
        context_text = "\n\n".join([
            f"[Nguồn: {doc['title']}]\n{doc['content']}"
            for doc in context
        ])

        response = self.openai.chat.completions.create(
            model="gpt-4.1-mini",
            messages=[
                {
                    "role": "system",
                    "content": "Bạn là một trợ lý hữu ích. Chỉ trả lờ dựa trên ngữ cảnh được cung cấp. Trích dẫn nguồn của bạn."
                },
                {
                    "role": "user",
                    "content": f"Ngữ cảnh:\n{context_text}\n\nCâu hỏi: {query}"
                }
            ],
            temperature=0.3,
            max_tokens=1000
        )
        return response.choices[0].message.content

    def chat(self, query: str) -> dict:
        """Pipeline RAG end-to-end."""
        context = self.retrieve(query)
        answer = self.generate(query, context)
        return {
            'query': query,
            'answer': answer,
            'sources': [doc['title'] for doc in context],
            'similarity_scores': [doc['similarity'] for doc in context]
        }

# Sử dụng
rag = SupabaseRAG(SUPABASE_URL, SUPABASE_KEY, OPENAI_KEY)
result = rag.chat("Các phương pháp hay nhất của Docker là gì?")
print(result['answer'])

-- Bật Row Level Security
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

-- Tạo chính sách: ngườ dùng chỉ có thể đọc tài liệu của họ
CREATE POLICY "Ngườ dùng có thể đọc tài liệu của họ"
ON documents FOR SELECT
USING (auth.uid() = user_id);

-- Tạo chính sách: ngườ dùng có thể chèn tài liệu của họ
CREATE POLICY "Ngườ dùng có thể chèn tài liệu của họ"
ON documents FOR INSERT
WITH CHECK (auth.uid() = user_id);

// Đăng ký ngườ dùng mới
const { data: authData, error: authError } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password-123'
})

// Đăng nhập
const { data: session } = await supabase.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password-123'
})

// Access token cho các lệnh gọi API
const accessToken = session.session?.access_token

-- Truy vấn với ngữ cảnh xác thực (RLS tự động thực thi)
const { data } = await supabase
  .from('documents')
  .select('*')

# Python: Xác thực phía server với service role key
supabase_admin = create_client(SUPABASE_URL, SERVICE_ROLE_KEY)

-- Bỏ qua RLS cho các thao tác quản trị
all_docs = supabase_admin.table('documents').select('*').execute()

// Đăng ký các thay đổi cơ sở dữ liệu thờ gian thực
const channel = supabase
  .channel('documents-changes')
  .on(
    'postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'documents' },
    (payload) => {
      console.log('Tài liệu mới được chèn:', payload.new)
      // Kích hoạt lập chỉ mục lại, thông báo, hoặc cập nhật UI
    }
  )
  .subscribe()

// Hủy đăng ký khi xong
supabase.removeChannel(channel)

# Python asyncio version
import asyncio

async def subscribe_to_changes():
    channel = supabase.channel('documents-changes')
    
    def handle_insert(payload):
        print(f"Tài liệu mới: {payload['new']['title']}")
    
    channel.on(
        'postgres_changes',
        {'event': 'INSERT', 'schema': 'public', 'table': 'documents'},
        handle_insert
    ).subscribe()

asyncio.run(subscribe_to_changes())

# Khởi tạo edge function
supabase functions new ai-completion

# Chỉnh sửa file đã tạo
# supabase/functions/ai-completion/index.ts

// supabase/functions/ai-completion/index.ts
import { serve } from 'https://deno.land/std@0.224.0/http/server.ts'

serve(async (req) => {
  const { prompt } = await req.json()

  // Gọi OpenAI API từ edge
  const response = await fetch('https://api.openai.com/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${Deno.env.get('OPENAI_API_KEY')}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4.1-mini',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 500
    })
  })

  const data = await response.json()

  return new Response(
    JSON.stringify({ completion: data.choices[0].message.content }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

# Đặt secrets
supabase secrets set OPENAI_API_KEY=sk-...

# Triển khai hàm
supabase functions deploy ai-completion

# Gọi qua HTTP
supabase functions invoke ai-completion --data '{"prompt": "Explain RAG"}'

# docker-compose.prod.yml (đoạn trích)
services:
  db:
    image: supabase/postgres:15.8.1.040
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGVECTOR_HNSW_EF_SEARCH: 64
    volumes:
      - pgdata:/var/lib/postgresql/data
    command: >
      postgres
        -c shared_preload_libraries='pg_stat_statements,pgvector'
        -c max_connections=200
        -c shared_buffers=2GB
        -c effective_cache_size=6GB
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  kong:
    image: kong:3.7
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /var/lib/kong/kong.yml
    ports:
      - "8000:8000"
    depends_on:
      - auth
      - rest
      - realtime

volumes:
  pgdata:

# File .env cho production
POSTGRES_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 32)
ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# SMTP cho email xác thực
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.xxx

# Lưu trữ tương thích S3
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_ENDPOINT=s3.amazonaws.com
STORAGE_S3_ACCESS_KEY=AKIA...
STORAGE_S3_SECRET_KEY=...

# Sao lưu hàng ngày tự động với pg_dump
0 2 * * * docker exec supabase-db pg_dump -U postgres -Fc postgres > /backups/supabase-$(date +\%Y\%m\%d).dump

# Hoặc sử dụng Khôi phục Điểm Thờ Gian (PITR) tích hợp sẵn của Supabase
# Có sẵn ở tier Pro trở lên

# Tạo migration mới
supabase migration new add_documents_table

# Chỉnh sửa file SQL đã tạo
# supabase/migrations/20260519000000_add_documents_table.sql

# Áp dụng cho instance cục bộ
supabase db reset

# Triển khai lên production
supabase db push

# Tạo kiểu TypeScript từ schema
supabase gen types typescript --local > src/types/supabase.ts