Wiki-RAG Guide

/path/to/vault/
├── 00-INDEX.md        # สารบัญ: ทุกหน้าต้องมีแถวในนี้
├── entities/          # ของจริง: server, service, โปรเจกต์, บัญชี
├── concepts/          # แพทเทิร์น / สถาปัตยกรรม
├── decisions/         # ADR: ตัดสินใจอะไร เพราะอะไร (YYYY-MM-DD--adr-NNN--title.md)
├── procedures/        # runbook ทีละขั้น
├── references/        # snippet / คำสั่งที่ใช้บ่อย
├── logs/              # บันทึกตามวัน (append-only)
└── sources/           # ข้อมูลดิบ ห้ามแก้

---
created: 2026-01-15
updated: 2026-03-02        # bump ทุกครั้งที่แก้เนื้อหา
tags: [postgres, backup]
category: procedure        # entity|concept|decision|procedure|source|log|reference
related: [[db-server]], [[backup-policy]]   # อย่างน้อย 1 ลิงก์
status: active             # draft|active|stale|archived
---
# หัวข้อหน้า

## ขั้นตอน
...

CREATE DATABASE wiki_rag WITH ENCODING 'UTF8'
  LC_COLLATE 'C.UTF-8' LC_CTYPE 'C.UTF-8' TEMPLATE template0;
\c wiki_rag
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (
  id          serial PRIMARY KEY,
  rel_path    text NOT NULL UNIQUE,   -- path สัมพัทธ์ใน vault = key
  title       text,
  content     text,                   -- ทั้งไฟล์ ไว้ให้ get_document
  doc_meta    jsonb,                  -- frontmatter
  ingested_at timestamptz DEFAULT now()
);

CREATE TABLE chunks (
  id          serial PRIMARY KEY,
  document_id integer NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
  chunk_index integer NOT NULL,
  heading     text,
  content     text,
  UNIQUE (document_id, chunk_index)
);

-- 1 ตาราง vector ต่อ 1 embedding model (ดู 4.8 การสลับ model)
CREATE TABLE chunk_embeddings_g2 (
  chunk_id  integer PRIMARY KEY REFERENCES chunks(id) ON DELETE CASCADE,
  embedding vector(768) NOT NULL
);
CREATE INDEX chunk_emb_g2_hnsw ON chunk_embeddings_g2
  USING hnsw (embedding vector_cosine_ops);

-- ไว้ให้ ingest ข้ามไฟล์ที่ไม่เปลี่ยน
CREATE TABLE ingest_state (
  rel_path    text PRIMARY KEY,
  mtime_ns    bigint NOT NULL,
  ingested_at timestamptz DEFAULT now()
);

POST http://<embed-host>:<port>/v1/embeddings
{ "input": ["title: A | text: ...", "..."], "input_type": "document" }   # หรือ "query"

200 OK
{ "data": [ {"index": 0, "embedding": [0.012, -0.044, ... 768 ค่า]}, ... ] }

import os, re, sys, json, argparse, requests, psycopg
from pgvector.psycopg import register_vector

MAX, OVERLAP, DIM = 1800, 120, 768
VAULT = os.environ["WIKI_SOURCE_DIR"]            # /path/to/vault
DSN   = os.environ["WIKI_DATABASE_URL"]          # postgresql://user:***@<db-host>:5432/wiki_rag
EMBED = os.environ["WIKI_EMBED_URL"]             # http://<embed-host>:<port>
SKIP_DIRS = {".git", ".obsidian", "node_modules"}

def split_sections(body):
    """คืน [(heading, text)] ตามหัวข้อ ## / ###"""
    parts, head, buf = [], "", []
    for line in body.splitlines():
        if re.match(r"^#{2,3} ", line):
            if buf: parts.append((head, "\n".join(buf).strip()))
            head, buf = line.lstrip("# ").strip(), []
        else:
            buf.append(line)
    if buf: parts.append((head, "\n".join(buf).strip()))
    return [p for p in parts if p[1]]

def chunk(text):
    if len(text) <= MAX: return [text]
    step = MAX - OVERLAP
    return [text[i:i+MAX] for i in range(0, len(text), step)]

def embed_docs(title_text_pairs):
    inputs = [f"title: {t or 'none'} | text: {x}" for t, x in title_text_pairs]
    r = requests.post(f"{EMBED}/v1/embeddings",
                      json={"input": inputs, "input_type": "document"}, timeout=900)
    r.raise_for_status()
    vecs = [d["embedding"] for d in sorted(r.json()["data"], key=lambda d: d["index"])]
    assert len(vecs) == len(inputs) and all(len(v) == DIM for v in vecs), "bad embedding shape"
    return vecs

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--only"); ap.add_argument("--force", action="store_true")
    args = ap.parse_args()
    with psycopg.connect(DSN) as conn:
        register_vector(conn); cur = conn.cursor()
        cur.execute("SELECT rel_path, mtime_ns FROM ingest_state")
        seen = dict(cur.fetchall())
        for root, dirs, files in os.walk(VAULT):
            dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
            for f in files:
                if not f.endswith(".md") or f.startswith("._"): continue
                path = os.path.join(root, f); rel = os.path.relpath(path, VAULT)
                if args.only and args.only not in rel: continue
                mt = os.stat(path).st_mtime_ns
                if not args.force and seen.get(rel) == mt: continue
                text = open(path, encoding="utf-8").read()
                title = (re.search(r"^# (.+)$", text, re.M) or [None, f])[1]
                rows = [(h, c) for h, s in split_sections(text) for c in chunk(s)]
                vecs = embed_docs([(title, c) for _, c in rows]) if rows else []
                cur.execute("""INSERT INTO documents (rel_path,title,content) VALUES (%s,%s,%s)
                  ON CONFLICT (rel_path) DO UPDATE SET title=EXCLUDED.title,
                  content=EXCLUDED.content, ingested_at=now() RETURNING id""", (rel, title, text))
                doc_id = cur.fetchone()[0]
                cur.execute("DELETE FROM chunks WHERE document_id=%s", (doc_id,))  # cascade ลบ vector
                for i, ((h, c), v) in enumerate(zip(rows, vecs)):
                    cur.execute("INSERT INTO chunks (document_id,chunk_index,heading,content) "
                                "VALUES (%s,%s,%s,%s) RETURNING id", (doc_id, i, h, c))
                    cur.execute("INSERT INTO chunk_embeddings_g2 VALUES (%s,%s)",
                                (cur.fetchone()[0], v))
                cur.execute("""INSERT INTO ingest_state (rel_path,mtime_ns) VALUES (%s,%s)
                  ON CONFLICT (rel_path) DO UPDATE SET mtime_ns=EXCLUDED.mtime_ns""", (rel, mt))
                conn.commit(); print("ingested", rel, len(rows), "chunks")

if __name__ == "__main__": main()

import os, json, subprocess, requests, psycopg
from fastmcp import FastMCP
from fastmcp.server.auth.providers.jwt import StaticTokenVerifier

TOKEN = os.environ["WIKI_MCP_TOKEN"]            # สุ่มยาวๆ เก็บใน env เท่านั้น
auth = StaticTokenVerifier(tokens={TOKEN: {"client_id": "agent", "scopes": []}})
mcp = FastMCP("wiki-rag", auth=auth)

DSN, EMBED = os.environ["WIKI_DATABASE_URL"], os.environ["WIKI_EMBED_URL"]

def embed_query(text):
    r = requests.post(f"{EMBED}/v1/embeddings",
                      json={"input": [text], "input_type": "query"}, timeout=30)
    r.raise_for_status()
    return r.json()["data"][0]["embedding"]

@mcp.tool()
def search_knowledge(query: str, limit: int = 5, min_score: float = 0.0) -> str:
    """Semantic search. Returns the most relevant chunks with source path and score."""
    limit = max(1, min(int(limit), 20))
    vec = str(embed_query(query))               # '[0.1,0.2,...]' → ::vector
    with psycopg.connect(DSN) as conn:
        rows = conn.execute("""
          SELECT c.content, c.heading, d.rel_path, d.title,
                 round((1 - (g.embedding <=> %s::vector))::numeric, 4) AS sim
          FROM chunk_embeddings_g2 g
          JOIN chunks c    ON c.id = g.chunk_id
          JOIN documents d ON d.id = c.document_id
          WHERE 1 - (g.embedding <=> %s::vector) >= %s
          ORDER BY g.embedding <=> %s::vector
          LIMIT %s""", (vec, vec, min_score, vec, limit)).fetchall()
    return json.dumps({"query": query, "results": [
        {"score": float(r[4]), "rel_path": r[2], "title": r[3],
         "heading": r[1], "content": r[0]} for r in rows]}, ensure_ascii=False)

@mcp.tool()
def get_document(rel_path: str) -> str:
    """Return one full document. Use only after search_knowledge points to it."""
    with psycopg.connect(DSN) as conn:
        row = conn.execute("SELECT title, content FROM documents WHERE rel_path=%s",
                           (rel_path,)).fetchone()
    return json.dumps({"rel_path": rel_path, "title": row[0], "content": row[1]}
                      if row else {"error": "not found"}, ensure_ascii=False)

@mcp.tool()
def list_documents() -> str:
    """List all indexed documents (path + title)."""
    with psycopg.connect(DSN) as conn:
        rows = conn.execute("SELECT rel_path, title FROM documents ORDER BY rel_path").fetchall()
    return json.dumps([{"rel_path": a, "title": b} for a, b in rows], ensure_ascii=False)

@mcp.tool()
def reindex(only: str = "") -> str:
    """Re-ingest changed files (optionally only paths containing `only`)."""
    cmd = ["python", "ingest.py"] + (["--only", only] if only else [])
    p = subprocess.run(cmd, capture_output=True, text=True, timeout=1800)
    return (p.stdout + p.stderr)[-2000:]

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000, path="/mcp")

[Unit]
Description=wiki-rag MCP server
After=network-online.target

[Service]
WorkingDirectory=/opt/wiki-rag
EnvironmentFile=/etc/wiki-rag.env        # chmod 600: WIKI_MCP_TOKEN, WIKI_DATABASE_URL, WIKI_EMBED_URL
ExecStart=/opt/wiki-rag/venv/bin/python mcp_server.py
Restart=on-failure
User=wikirag

[Install]
WantedBy=multi-user.target

export WIKI_MCP_TOKEN='...'   # ค่าจริงเก็บนอก repo
claude mcp add --transport http wiki-rag http://<mcp-host>:8000/mcp \
  --header "Authorization: Bearer $WIKI_MCP_TOKEN"
claude mcp list              # ต้องเห็น wiki-rag: connected

./venv/bin/python ingest.py                    # incremental: เฉพาะไฟล์ที่ mtime เปลี่ยน
./venv/bin/python ingest.py --only procedures/ # เฉพาะ path ที่มีข้อความนี้
./venv/bin/python ingest.py --force            # ทำใหม่ทั้งหมด (ต้องใช้เมื่อเปลี่ยน model/chunking)

PROVIDERS = {
  "new": {"table": "chunk_embeddings_g2", "dim": 768,  "embed": embed_query_new},
  "old": {"table": "chunks_embedding_old", "dim": 1024, "embed": embed_query_old},
}
P = PROVIDERS[os.environ.get("WIKI_SEARCH_PROVIDER", "new")]
# SQL ใน search_knowledge ใช้ P["table"]; rollback = ตั้ง env กลับ + restart

## Project knowledge (ทำตามลำดับ)
1. ก่อนอ่านไฟล์หรือถามผู้ใช้ ให้เรียก MCP tool `search_knowledge("<คำถาม>")` ก่อนเสมอ
2. ถ้าผลมี score < 0.5 หรือไม่ตรงคำถาม ให้ลองเปลี่ยนคำค้น 1-2 ครั้ง แล้วค่อยบอกว่าไม่พบ
3. เรียก `get_document(rel_path)` เฉพาะเมื่อ chunk ที่ได้ไม่พอ (ไฟล์เต็มกินหลาย KB)
4. ตอบพร้อมอ้างอิง rel_path ของหน้าที่ใช้
5. ถ้าข้อเท็จจริงมีอยู่ใน wiki แล้ว ตอบจาก wiki ห้ามไล่อ่านโค้ด/log ใหม่
6. เมื่อค้นพบความรู้ใหม่ ให้เขียนลง vault แล้ว `reindex(only="<path>")` (ดูหัวข้อ 5.3)
7. ห้ามเขียน secret (password/API key/token) ลง vault

{
  "name": "search_knowledge",
  "arguments": { "query": "วิธีสำรองฐานข้อมูลก่อน migrate", "limit": 3 }
}

{
  "query": "วิธีสำรองฐานข้อมูลก่อน migrate",
  "results": [
    {
      "score": 0.7412,
      "rel_path": "procedures/db-backup-before-migrate.md",
      "title": "สำรอง DB ก่อน migrate",
      "heading": "ขั้นตอน",
      "content": "1. รัน pg_dump -Fc ... 2. ตรวจขนาดไฟล์ไม่เป็นศูนย์ 3. ..."
    },
    {
      "score": 0.6120,
      "rel_path": "decisions/2026-03-01--adr-002--backup-policy.md",
      "title": "ADR-002: นโยบายสำรองข้อมูล",
      "heading": "การตัดสินใจ",
      "content": "สำรองทุกคืน เก็บ 14 วัน ..."
    }
  ]
}