Metadata-Version: 2.4
Name: fatcat-gpt
Version: 0.1.6
Summary: 胖貓專屬嘴臭LLM推理API
Author: caster97
Description-Content-Type: text/markdown
Requires-Dist: torch==2.8.0
Requires-Dist: unsloth==2026.5.8
Requires-Dist: peft==0.19.1
Requires-Dist: transformers==4.56.2
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: pydantic
Requires-Dist: requests
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: summary

# 🐈 FatCat GPT API

這是一個基於 FastAPI 與 `fatcat-gpt` 套件建構的大型語言模型 (LLM) 推理伺服器。
模型被設定為一個名叫咪咪的 Discord 活躍群友，講話直接，而且專門給出讓人心情更糟的超臭回覆。

透過這個專案，模型只會在伺服器啟動時載入顯示卡一次，之後便可在背景待命，隨時接收 API 請求並瞬間給出回覆，可以用來串接 Discord 機器人。

---

## 🛠️ 環境與安裝清單

請確保你的環境中已經安裝了 `fatcat-gpt` 核心套件以及 API 所需的依賴模組：

```bash
# 確保已安裝 fatcat-gpt
pip install fatcat-gpt
```
## 🚀 快速啟動指南

這個專案分為「伺服器端 (Server)」與「測試端 (Client)」兩個部分。

### 第一步：啟動背景伺服器 (`server.py`)

伺服器負責將幾十 GB 的模型載入 GPU 中並保持待命。請在終端機中執行以下指令來啟動 API 伺服器：

```bash
uvicorn server:app --host 0.0.0.0 --port 8000
```
💡 提示 (多顯卡環境)： > 如果你的機器有多張顯卡，且你想把模型強制綁定在特定的 GPU (例如 GPU 0)，請在指令前面加上環境變數：
```bash
CUDA_VISIBLE_DEVICES=0 uvicorn server:app --host 0.0.0.0 --port 8000
```

server.py
```py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Dict
from contextlib import asynccontextmanager
from fatcat_gpt import FatCatGPT

bot = None

# =========================================================
# start server
# =========================================================
@asynccontextmanager
async def lifespan(app: FastAPI):
    global bot
    print("[伺服器啟動中] 正在將模型載入到背景，請稍候...")
    bot = FatCatGPT()
    print("[伺服器已就緒] 胖貓模型載入完成，等待呼叫！")
    yield
    print("[伺服器關閉中] 正在釋放顯示卡記憶體...")
    bot = None

app = FastAPI(title="FatCat GPT API", lifespan=lifespan)

class ChatRequest(BaseModel):
    messages: List[Dict[str, str]]
    max_new_tokens: int = 128
    temperature: float = 0.3
    top_p: float = 0.95

# =========================================================
# Endpoint: /chat
# =========================================================
@app.post("/chat")
async def chat_endpoint(request: ChatRequest):
    if bot is None:
        raise HTTPException(status_code=500, detail="模型尚未載入完成")
    
    try:
        response = bot.chat(
            messages=request.messages,
            max_new_tokens=request.max_new_tokens,
            temperature=request.temperature,
            top_p=request.top_p
        )
        return {"status": "success", "response": response}
    
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))
```

等待終端機印出 [伺服器已就緒] 或類似的成功訊息後，就代表伺服器已經成功啟動並駐留在背景。請將這個終端機視窗保持開啟，不要關閉。

### 第二步：發送測試請求 (send.py)
請開啟另一個新的終端機視窗，執行測試腳本，向剛才開好的伺服器發送對話內容：

```bash
python send.py
```

send.py
```py
import requests

API_URL = "http://127.0.0.1:8000/chat"

payload = {
    "messages": [
        {
          "role": "user",
          "content": "user_id_a: 今天晚餐吃什麼好？"
        }
    ],
    "temperature": 0.5 
}

print("發送請求中...")
response = requests.post(API_URL, json=payload)

if response.status_code == 200:
    data = response.json()
    print("FatCat:", data["response"])
else:
    print("發生錯誤:", response.text)
```
如果一切順利，你將會瞬間在終端機看到來自咪咪的無情臭人回覆！

## 📡 API 規格說明
伺服器啟動後，預設會監聽 http://127.0.0.1:8000。

POST /chat
接收對話歷史並回傳咪咪生成的文字。

請求格式 (JSON payload):

```JSON
{
  "messages": [
    {
      "role": "user",
      "content": "user_id_a: 今天晚餐吃什麼好？"
    }
  ],
  "max_new_tokens": 128,
  "temperature": 0.3,
  "top_p": 0.95
}
```
成功回應格式 (JSON):

```JSON
{
  "status": "success",
  "response": "咪咪生成的無情回覆字串"
}
```
