从零搭建高尔夫规则 AI 问答系统：完整记录与踩坑清单

WordPress 页面（golforfun.net）
   ↓ HTTPS POST
api.golforfun.net（nginx 443，Let's Encrypt 证书）
   ↓
FastAPI（127.0.0.1:8090，频率限制 + 缓存 + 长度限制）
   ↓
LangGraph Agentic RAG
   ├─ 检索：Chroma 向量库（303 条规则子条款）
   ├─ 评分：DeepSeek 判断条款是否相关
   └─ 生成：DeepSeek 输出结构化 JSON（罚杆数 + 依据 + 解释）
   ↓
One API（127.0.0.1:3000/v1）→ DeepSeek 上游

mkdir -p /opt/golf-rag && cd /opt/golf-rag
python3 -m venv venv
source venv/bin/activate
pip install langgraph langchain-openai langchain-community pypdf chromadb
pip install sentence-transformers langchain-huggingface langchain-chroma
pip install fastapi uvicorn

import re, shutil, os
from pypdf import PdfReader
from langchain_core.documents import Document
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma

reader = PdfReader("golfrule2023.pdf")
full = "\n".join((p.extract_text() or "") for p in reader.pages)

# 跳过目录：找第二次出现的「如何使用高爾夫規則」
idx = full.find("如何使用高爾夫規則")
idx2 = full.find("如何使用高爾夫規則", idx + 10)
full = full[idx2:] if idx2 != -1 else full[idx:]

# 找所有「規則 X 标题」的位置（只取第一次，排除页眉）
rule_starts = {}
for mm in re.finditer(r"^規則\s+(\d+)\s+[^\d\s]", full, flags=re.M):
    rno = mm.group(1)
    if rno not in rule_starts:
        rule_starts[rno] = mm.start()

# 在全文上找所有子条款编号「X.Y[a-z]?」在行首
sub_positions = []
for mm in re.finditer(r"^(\d+)\.(\d+[a-z]?)", full, flags=re.M):
    rno, sub = mm.group(1), mm.group(2)
    if rno in rule_starts:
        sub_positions.append((mm.start(), rno, f"{rno}.{sub}"))

# 按子条款位置切
sub_positions.sort()
docs = []
for i, (pos, rno, sub_no) in enumerate(sub_positions):
    end = sub_positions[i+1][0] if i+1 < len(sub_positions) else len(full)
    seg = full[pos:end].strip()
    if len(seg) < 60:
        continue
    rule_title = ""
    rs = rule_starts.get(rno, -1)
    if rs != -1:
        tm = re.match(r"規則\s+\d+\s+(.+)", full[rs:rs+100])
        if tm:
            rule_title = tm.group(1).split("\n")[0].strip()[:60]
    rest = re.sub(rf"^{re.escape(sub_no)}", "", seg).strip()
    sub_title = rest.split("\n")[0].strip()[:50]
    content = f"規則 {rno}（{rule_title}）\n{sub_no} {sub_title}\n\n{seg}"
    docs.append(Document(
        page_content=content,
        metadata={"rule": f"規則 {rno}", "sub": sub_no, "title": rule_title}
    ))

print(f"拆出 {len(docs)} 个子条款")
if os.path.exists("./chroma_db"):
    shutil.rmtree("./chroma_db")
emb = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5")
Chroma.from_documents(docs, emb, persist_directory="./chroma_db")

SYNONYMS = {
    "红桩": "紅色處罰區 側面脫困", "紅樁": "紅色處罰區 側面脫困",
    "红色": "紅色處罰區", "紅色": "紅色處罰區",
    "黄桩": "黃色處罰區", "黃樁": "黃色處罰區",
    "出界": "界外 遺失球", "界外": "界外 遺失球",
    "被踩": "被移動 靜止球", "移動": "被移動 靜止球",
    "旗杆": "旗桿 果嶺", "旗桿": "旗桿 果嶺",
    "抛球": "脫困 拋球", "拋球": "脫困 拋球",
    "沙坑": "沙坑", "OB": "界外 遺失球",
    "下水": "處罰區 水障礙", "水障碍": "處罰區 水障礙",
}

def expand(q):
    extra = [v for k, v in SYNONYMS.items() if k in q]
    return (q + " " + " ".join(extra)).strip() if extra else q

KEYWORD_RULE_MAP = [
    (["红桩", "紅樁", "红区", "紅色處罰區", "罚杆区", "罰桿區"], "規則 17"),
    (["沙坑"], "規則 12"),
    (["果岭", "果嶺", "旗杆", "旗桿"], "規則 13"),
    (["出界", "界外", "OB", "遗失球", "遺失球"], "規則 18"),
    (["暂定球", "暫定球"], "規則 18"),
    (["无法打", "無法打"], "規則 19"),
]

forced_rule = None
for kws, rule in KEYWORD_RULE_MAP:
    if any(k in query for k in kws):
        forced_rule = rule
        break

if forced_rule:
    docs = vs.similarity_search(eq, k=3, filter={"rule": forced_rule})
else:
    docs1 = vs.similarity_search(eq, k=3)
    docs2 = vs.similarity_search(query, k=3)
    seen = set()
    docs = []
    for d in docs1 + docs2:
        key = (d.metadata["rule"], d.metadata["sub"])
        if key not in seen:
            seen.add(key)
            docs.append(d)
    docs = docs[:4]

START → generate_query_or_respond（决定检索）
      → retrieve（检索）
      → grade_documents（评分）
         ├─ yes → generate_answer → END
         └─ no  → rewrite_question → 回到 generate_query_or_respond

def rewrite_question(state):
    q = state["messages"][0].content
    rewrites = sum(1 for m in state["messages"] if isinstance(m, HumanMessage)) - 1
    if rewrites >= 2:
        return {"messages": [HumanMessage(content=q)]}
    resp = make_llm().invoke(f"把下面的高爾夫規則問題改寫成更適合檢索規則條款的形式，只輸出改寫後的問題：\n{q}")
    return {"messages": [HumanMessage(content=resp.content)]}

GENERATE_PROMPT = """你是高爾夫規則顧問。只根據下面檢索到的條款回答問題。

要求：
1. 必須明確回答「是否罰桿」和「罰幾桿」（0=不罰，1=罰一桿，2=罰二桿，null=條款未明確）。
2. 如果條款裡有「罰一桿」「一般處罰」「不罰」等字樣，按條款給出數字。
3. 如果條款沒有明確寫處罰數量，penalty_strokes 設為 null，並在 explanation 裡說明。
4. 引用規則編號。
5. 不要編造條款裡沒有的內容。
6. 如果問題涉及開球出界（OB）或球遺失，在 explanation 末尾補充：若球場啟用當地規則 E-5，可選擇罰 2 桿在球道附近拋球。

以純 JSON 輸出（不要加 markdown 代碼塊），格式：
{"is_penalty": true/false, "penalty_strokes": 0/1/2/null, "rule_ref": "規則 X.Y", "explanation": "..."}

檢索到的條款：
{context}

用戶問題：{question}"""

ONEAPI_BASE = "http://127.0.0.1:3000/v1"
ONEAPI_KEY = "sk-..."  # One API 令牌
MODEL = "deepseek-ai/deepseek-v4.1-flash"

def make_llm(temperature=0):
    return ChatOpenAI(
        base_url=ONEAPI_BASE, api_key=ONEAPI_KEY, model=MODEL,
        temperature=temperature, timeout=300,
    )

import sqlite3, hashlib, time
from collections import defaultdict
from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel, Field
from agent import graph
from langchain_core.messages import HumanMessage

app = FastAPI()

_rate = defaultdict(list)
RATE_LIMIT = 3
RATE_WINDOW = 60
CACHE_DB = "/opt/golf-rag/cache.db"

def _init_cache():
    conn = sqlite3.connect(CACHE_DB)
    conn.execute("CREATE TABLE IF NOT EXISTS cache (hash TEXT PRIMARY KEY, answer TEXT, ts REAL)")
    conn.commit(); conn.close()

_init_cache()

def cache_get(q):
    h = hashlib.md5(q.strip().lower().encode()).hexdigest()
    conn = sqlite3.connect(CACHE_DB)
    row = conn.execute("SELECT answer FROM cache WHERE hash=?", (h,)).fetchone()
    conn.close()
    return row[0] if row else None

def cache_set(q, a):
    h = hashlib.md5(q.strip().lower().encode()).hexdigest()
    conn = sqlite3.connect(CACHE_DB)
    conn.execute("INSERT OR REPLACE INTO cache (hash, answer, ts) VALUES (?,?,?)", (h, a, time.time()))
    conn.commit(); conn.close()

class Question(BaseModel):
    text: str = Field(..., min_length=2, max_length=200)

@app.post("/api/golf-rules")
async def ask(q: Question, request: Request):
    ip = request.headers.get("X-Real-IP", request.client.host)
    now = time.time()
    _rate[ip] = [t for t in _rate[ip] if now - t < RATE_WINDOW]
    if len(_rate[ip]) >= RATE_LIMIT:
        raise HTTPException(status_code=429, detail="请求太频繁，请稍后再试（每分钟最多 3 次）")
    _rate[ip].append(now)

    cached = cache_get(q.text)
    if cached:
        return {"answer": cached, "cached": True}

    r = graph.invoke({"messages": [HumanMessage(content=q.text)]})
    answer = r["messages"][-1].content
    cache_set(q.text, answer)
    return {"answer": answer, "cached": False}

[Unit]
Description=Golf Rules RAG API
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/golf-rag
ExecStart=/opt/golf-rag/venv/bin/uvicorn api:app --host 127.0.0.1 --port 8090
Restart=on-failure
RestartSec=5
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now golf-rag

api.golforfun.net  A  162.43.92.249  TTL 3600

server {
    listen 80;
    server_name api.golforfun.net;
    return 301 https://$host$request_uri;
}

server {
    listen 162.43.92.249:443 ssl;
    server_name api.golforfun.net;

    ssl_certificate /etc/letsencrypt/live/api.golforfun.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.golforfun.net/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location /api/golf-rules {
        add_header 'Access-Control-Allow-Origin' 'https://golforfun.net' always;
        add_header 'Access-Control-Allow-Methods' 'POST, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'Content-Type' always;
        if ($request_method = 'OPTIONS') {
            return 204;
        }
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
        proxy_connect_timeout 10s;
    }
}

certbot certonly --manual \
  -d api.golforfun.net \
  --preferred-challenges dns \
  --agree-tos --register-unsafely-without-email

# 证书文件
ls -la /etc/letsencrypt/live/api.golforfun.net/

# 443 监听
ss -ltnp | grep ':443 '

# 公网 HTTPS 测试（--resolve 绕过 DNS 缓存）
curl -s --resolve api.golforfun.net:443:162.43.92.249 \
  -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}'

from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://golforfun.net", "https://www.golforfun.net"],
    allow_methods=["POST", "OPTIONS"],
    allow_headers=["Content-Type"],
)

(["当地规则", "當地規則", "附录", "附錄"], "附錄 A"),

cd /opt/golf-rag
./kb_manage.sh count

主库条数：303

./kb_manage.sh test "红桩怎么抛球"

查询：红桩怎么抛球
扩展后：红桩怎么抛球 紅色處罰區 側面脫困 脫困 拋球
硬过滤：規則 17
  [規則 17 17.1d] 處罰區
  [規則 17 17.2a] 處罰區
  [規則 17 17.1e] 處罰區

./kb_manage.sh test "开球出界了怎么算"
# 应命中 規則 18

./kb_manage.sh test "球打进沙坑怎么办"
# 应命中 規則 12

./kb_manage.sh test "推杆时球碰到旗杆"
# 应命中 規則 13

./kb_manage.sh test "球停在cart path上怎么办"
# 可能命中 規則 16（异常状况），如果不准，往 SYNONYMS 加词

cat > appendix_a.txt <<'EOF'
附錄 A 當地規則範例

A.1 優先順序
當地規則的優先順序高於規則本身，但不得違反規則的基本原則。委員會可採用當地規則以應對特殊情況，例如臨時積水、環保敏感區域、球道上的不可移動障礙物等。

A.2 常見當地規則
- 球道上的不可移動障礙物：免罰脫困
- 臨時積水：視為異常狀況，免罰脫困
- 環保敏感區域：禁止進入，必須脫困
EOF

./kb_manage.sh add appendix_a.txt "附錄 A" "A.1" "當地規則範例"

✅ 已追加 [附錄 A A.1] 當地規則範例，当前库 304 条

./kb_manage.sh count
# 应显示 304

./kb_manage.sh test "当地规则优先顺序"
# 可能命中 [附錄 A A.1]，也可能不命中（因为 KEYWORD_RULE_MAP 里没有「附錄 A」的映射）

# 把新版 PDF 传到 VPS
scp golfrule2024.pdf root@162.43.92.249:/opt/golf-rag/

cd /opt/golf-rag
./kb_manage.sh rebuild golfrule2024.pdf

📦 旧库备份到 chroma_db.bak.1792365000
拆出 320 个子条款
✅ Chroma 已写入 320 条
🧹 清缓存
✅ 重建完成，服务已重启

./kb_manage.sh count
# 应显示 320

./kb_manage.sh test "红桩怎么抛球"
# 应命中 規則 17

curl -s -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}' | head -c 300
# 应返回新规则的答案

cd /opt/golf-rag
ls -t chroma_db.bak.* | head -1
# 假设是 chroma_db.bak.1792365000
rm -rf chroma_db
mv chroma_db.bak.1792365000 chroma_db
systemctl restart golf-rag

cat > etiquette.txt <<'EOF'
高尔夫礼仪要点：

1. 安全第一：挥杆前确认周围无人，球可能打到人时大声喊「看球」。
2. 保持安静：他人击球时不要说话、不要走动。
3. 修复球痕：球落在果岭上留下的球痕要用球叉修复。
4. 耙平沙坑：从沙坑击球后，用沙耙把沙坑耙平。
5. 控制速度：不拖延打球节奏，让后面组跟上。
6. 着装规范：遵守球场的着装要求，通常要求有领上衣和 golf 鞋。
EOF

./kb_manage.sh newcol etiquette etiquette.txt "禮儀" "高爾夫禮儀"

✅ 已写入 collection 'etiquette'，当前 1 条
   注意：agent.py 里要加逻辑查这个 collection 才能用

./kb_manage.sh add etiquette.txt "禮儀" "E.1" "高爾夫禮儀"

curl -s --resolve api.golforfun.net:443:162.43.92.249 \
  -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}'

curl -s -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d '{"text":"开球出界了怎么算？罚几杆？"}'

time curl -s -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}'

for i in 1 2 3 4; do
  curl -s -o /dev/null -w "第 $i 次: HTTP %{http_code}\n" \
    -X POST https://api.golforfun.net/api/golf-rules \
    -H "Content-Type: application/json" \
    -d '{"text":"红桩怎么抛球？罚几杆？"}'
done

第 1 次: HTTP 200
第 2 次: HTTP 200
第 3 次: HTTP 200
第 4 次: HTTP 429

LONG=$(python3 -c "print('啊'*201)")
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d "{\"text\":\"$LONG\"}"

curl -s -X OPTIONS https://api.golforfun.net/api/golf-rules \
  -H "Origin: https://golforfun.net" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type" \
  -D - -o /dev/null | grep -iE "HTTP/|access-control"

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://golforfun.net
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

systemctl status golf-rag --no-pager | head -10

systemctl restart golf-rag

journalctl -u golf-rag -f

INFO:     127.0.0.1:xxxxx - "POST /api/golf-rules HTTP/1.1" 200 OK

journalctl -u golf-rag -n 50 --no-pager

tail -20 /var/log/nginx/error.log

sqlite3 /opt/golf-rag/cache.db "SELECT COUNT(*) FROM cache;"

sqlite3 /opt/golf-rag/cache.db "SELECT ts, answer FROM cache ORDER BY ts DESC LIMIT 5;"

rm /opt/golf-rag/cache.db
systemctl restart golf-rag

# 先算 hash
python3 -c "import hashlib; print(hashlib.md5('红桩怎么抛球？罚几杆？'.lower().encode()).hexdigest())"

# 假设输出是 abc123...
sqlite3 /opt/golf-rag/cache.db "DELETE FROM cache WHERE hash='abc123...';"

certbot certificates

Certificate Name: api.golforfun.net
  Domains: api.golforfun.net
  Expiry Date: 2027-01-17 (VALID: 89 days)
  Certificate Path: /etc/letsencrypt/live/api.golforfun.net/fullchain.pem
  Private Key Path: /etc/letsencrypt/live/api.golforfun.net/privkey.pem

certbot certonly --manual \
  -d api.golforfun.net \
  --preferred-challenges dns \
  --agree-tos --register-unsafely-without-email

ss -ltnp | grep ':443 '

curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  http://127.0.0.1:3000/v1/models

ss -ltnp | grep 8090

curl -s -X POST http://127.0.0.1/api/golf-rules \
  -H "Host: api.golforfun.net" \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球"}'

dig +short api.golforfun.net @8.8.8.8

curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  --resolve api.golforfun.net:443:162.43.92.249 \
  https://api.golforfun.net/api/golf-rules \
  -X POST -H "Content-Type: application/json" \
  -d '{"text":"test"}'

ufw status | grep 443

cat > /opt/golf-rag/e2e_test.sh <<'EOF'
#!/usr/bin/env bash
API="https://api.golforfun.net/api/golf-rules"
IP="162.43.92.249"
DOMAIN="api.golforfun.net"

echo "=== 1. DNS ==="
dig +short $DOMAIN @8.8.8.8

echo "=== 2. 443 监听 ==="
ss -ltnp | grep ':443 '

echo "=== 3. UFW 443 ==="
ufw status | grep 443 || echo "⚠️ 443 未放行"

echo "=== 4. 服务状态 ==="
systemctl is-active golf-rag

echo "=== 5. 证书 ==="
certbot certificates 2>/dev/null | grep -A2 "api.golforfun.net" | head -3

echo "=== 6. API 测试 ==="
curl -s --resolve $DOMAIN:443:$IP \
  -X POST $API \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}' | head -c 200

echo ""
echo "=== 7. 缓存命中 ==="
curl -s --resolve $DOMAIN:443:$IP \
  -X POST $API \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}' \
  -w "\n耗时 %{time_total}s\n" | tail -3

echo "=== 完成 ==="
EOF
chmod +x /opt/golf-rag/e2e_test.sh
/opt/golf-rag/e2e_test.sh