pj_llama/操作指南.md

# Llama API 連接操作指南

## 一、API 連接資訊

### API 金鑰
```
paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo=
```

### 可用端點

#### 主要外網端點
| 端點名稱 | URL | 狀態 | 支援模型 |
|---------|-----|------|---------|
| 通用端點 | https://llama.theaken.com/v1 | 🌐 主要 | gpt-oss-120b, deepseek-r1-671b, qwen3-embedding-8b |
| GPT-OSS 專用 | https://llama.theaken.com/v1/gpt-oss-120b | 🌐 主要 | gpt-oss-120b |
| DeepSeek 專用 | https://llama.theaken.com/v1/deepseek-r1-671b | 🌐 主要 | deepseek-r1-671b |

#### 備用外網端點
| 端點名稱 | URL | 狀態 | 支援模型 |
|---------|-----|------|---------|
| 備用 API 1 | https://api.llama.theaken.com/v1 | 🔄 備用 | 所有模型 |
| 備用 API 2 | https://llama-api.theaken.com/v1 | 🔄 備用 | 所有模型 |

## 二、快速開始

### 1. 安裝依賴
```bash
pip install openai
```

### 2. 測試連接（Python）

#### 外網連接範例
```python
from openai import OpenAI

# 設定 API
API_KEY = "paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo="
BASE_URL = "https://llama.theaken.com/v1"  # 使用外網端點

# 創建客戶端
client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL
)

# 發送請求
response = client.chat.completions.create(
    model="gpt-oss-120b",
    messages=[
        {"role": "user", "content": "你好，請自我介紹"}
    ],
    temperature=0.7,
    max_tokens=200
)

# 顯示回應
print(response.choices[0].message.content)
```

## 三、使用現成程式

### 程式清單
1. **llama_full_api.py** - 完整對話程式（支援內外網）
2. **llama_chat.py** - 內網專用對話程式
3. **local_api_test.py** - 端點測試工具
4. **quick_test.py** - 快速測試腳本

### 執行對話程式
```bash
# 執行完整版（自動測試所有端點）
python llama_full_api.py

# 執行內網版
python llama_chat.py

# 快速測試
python quick_test.py
```

## 四、對話程式使用說明

### 基本操作
1. 執行程式後會自動測試可用端點
2. 選擇要使用的端點（輸入數字）
3. 選擇要使用的模型
4. 開始對話

### 對話中指令
- `exit` 或 `quit` - 結束對話
- `clear` - 清空對話歷史
- `model` - 切換模型

## 五、常見問題處理

### 問題 1：502 Bad Gateway
**原因**：外網 API 伺服器離線  
**解決**：使用內網端點

### 問題 2：Connection Error
**原因**：不在內網環境或 IP 錯誤  
**解決**：
1. 確認在同一網路環境
2. 檢查防火牆設定
3. ping 192.168.0.6 測試連通性

### 問題 3：編碼錯誤
**原因**：Windows 終端編碼問題  
**解決**：使用英文對話或修改終端編碼

### 問題 4：回應包含特殊標記
**說明**：如 `<think>`, `<|channel|>` 等  
**處理**：程式已自動過濾這些標記

## 六、API 回應格式清理

部分模型回應可能包含思考過程標記，程式會自動清理：
- `<think>...</think>` - 思考過程
- `<|channel|>...<|message|>` - 通道標記
- `<|end|>`, `<|start|>` - 結束/開始標記

## 七、測試結果摘要

### 成功測試
✅ 內網端點 1-3 全部正常運作  
✅ 支援 OpenAI SDK 標準格式  
✅ 可正常進行對話  

### 待確認
- 外網端點需等待伺服器恢復
- DeepSeek 和 Qwen 模型需進一步測試

## 八、技術細節

### 使用 OpenAI SDK
```python
from openai import OpenAI

client = OpenAI(
    api_key="你的金鑰",
    base_url="API端點URL"
)
```

### 使用 requests 庫
```python
import requests

headers = {
    "Authorization": "Bearer 你的金鑰",
    "Content-Type": "application/json"
}

data = {
    "model": "gpt-oss-120b",
    "messages": [{"role": "user", "content": "你好"}],
    "temperature": 0.7,
    "max_tokens": 200
}

response = requests.post(
    "API端點URL/chat/completions",
    headers=headers,
    json=data
)
```

## 九、建議使用方式

1. **開發測試**：使用內網端點（速度快、穩定）
2. **生產環境**：配置多個端點自動切換
3. **對話應用**：使用 llama_full_api.py
4. **API 整合**：參考 quick_test.py 的實現

---

最後更新：2025-09-19  
測試環境：Windows / Python 3.13