# 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 |

## 二、快速開始

### 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_chat.py** - 主要對話程式（智慧連接）
2. **llama_full_api.py** - 完整對話程式（多端點支援）
3. **quick_test.py** - 快速測試腳本
4. **test_all_models.py** - 模型測試工具

### 執行對話程式
```bash
# 執行主程式（智慧對話）
python llama_chat.py

# 執行完整版（自動測試所有端點）
python llama_full_api.py

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

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

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

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

## 五、常見問題處理

### 問題 1：502 Bad Gateway
**原因**：API 伺服器暫時離線  
**解決**：稍後再試，程式會自動測試所有端點

### 問題 2：Connection Error
**原因**：網路連接問題  
**解決**：
1. 確認網路連接正常
2. 檢查防火牆或代理設定
3. 確認可以訪問 https://llama.theaken.com

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

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

## 六、API 回應格式清理

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

## 七、測試結果摘要

### 測試狀態
📡 API 端點連接測試中  
✅ 支援 OpenAI SDK 標準格式  
✅ 自動端點選擇機制  

### 支援功能
- 自動端點選擇
- 智慧超時控制
- 完整錯誤處理
- 多模型支援（GPT-OSS、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