从零搭建高尔夫规则 RAG 问答系统（LangGraph + Chroma + One API + FastAPI）

WordPress 页面（golforfun.net）
   ↓ HTTPS POST
api.golforfun.net（nginx 反代，443）
   ↓
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:
    # 双路检索：扩展 query + 原始 query，取并集
    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,
    )

from fastapi import FastAPI
from pydantic import BaseModel
from agent import graph
from langchain_core.messages import HumanMessage

app = FastAPI()

class Question(BaseModel):
    text: str

@app.post("/api/golf-rules")
async def ask(q: Question):
    r = graph.invoke({"messages": [HumanMessage(content=q.text)]})
    return {"answer": r["messages"][-1].content}

[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;

    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;
    }
}

snap install --classic certbot
ln -sf /snap/bin/certbot /usr/bin/certbot
certbot --nginx -d api.golforfun.net --non-interactive --agree-tos --register-unsafely-without-email

# 本地测（Host 头模拟公网）
curl -s -X POST http://127.0.0.1/api/golf-rules \
  -H "Host: api.golforfun.net" \
  -H "Content-Type: application/json" \
  -d '{"text":"红桩怎么抛球？罚几杆？"}'

# 公网 HTTPS 测
curl -s -X POST https://api.golforfun.net/api/golf-rules \
  -H "Content-Type: application/json" \
  -d '{"text":"沙坑里球旁边有石子能捡吗"}'