Initial commit with Llama API client and docs

Add Python scripts for Llama API chat clients, endpoint testing, and quick tests. Include documentation (README, CONTRIBUTING, 操作指南), license, and .gitignore. Supports multiple endpoints and models for OpenAI-compatible Llama API usage.
2025-09-19 21:44:02 +08:00
parent 4e28c131d2
commit 8a929936ad
18 changed files with 2073 additions and 0 deletions
--- a/操作指南.md
+++ b/操作指南.md
@@ -0,0 +1,181 @@
+# Llama API 連接操作指南
+
+## 一、API 連接資訊
+
+### API 金鑰
+```
+paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo=
+```
+
+### 可用端點
+
+#### 內網端點（已測試成功）
+| 端點名稱 | URL | 狀態 | 支援模型 |
+|---------|-----|------|---------|
+| 內網端點 1 | http://192.168.0.6:21180/v1 | ✅ 可用 | gpt-oss-120b, deepseek-r1-671b, qwen3-embedding-8b |
+| 內網端點 2 | http://192.168.0.6:21181/v1 | ✅ 可用 | gpt-oss-120b, deepseek-r1-671b, qwen3-embedding-8b |
+| 內網端點 3 | http://192.168.0.6:21182/v1 | ✅ 可用 | gpt-oss-120b, deepseek-r1-671b, qwen3-embedding-8b |
+| 內網端點 4 | http://192.168.0.6:21183/v1 | ❌ 錯誤 | 500 Internal Server Error |
+
+#### 外網端點（待測試）
+| 端點名稱 | URL | 狀態 | 支援模型 |
+|---------|-----|------|---------|
+| 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 |
+| 通用端點 | https://llama.theaken.com/v1 | 待測試 | 所有模型 |
+
+## 二、快速開始
+
+### 1. 安裝依賴
+```bash
+pip install openai
+```
+
+### 2. 測試連接（Python）
+
+#### 內網連接範例
+```python
+from openai import OpenAI
+
+# 設定 API
+API_KEY = "paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo="
+BASE_URL = "http://192.168.0.6:21180/v1"  # 使用內網端點 1
+
+# 創建客戶端
+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