更新 README.md 為中文版本

- 改為簡單易懂的中文說明 - 加入詳細的使用教學 - 增加常見問題解答 - 提供範例程式碼 - 加入 emoji 讓內容更生動
2025-09-19 21:59:47 +08:00
parent 5f191571d9
commit 34fcf39fda
1 changed files with 166 additions and 164 deletions
--- a/README.md
+++ b/README.md
@@ -1,201 +1,203 @@
-# Llama API Client
+# Llama AI 對話程式

-A Python client for connecting to Llama AI models through OpenAI-compatible API endpoints.
+一個簡單易用的 Python 程式，用於連接和使用 Llama AI 模型進行對話。

-## Features
+## 🌟 主要功能

- 🌐 Support for both internal network and external API endpoints
- 🤖 Multiple model support (GPT-OSS-120B, DeepSeek-R1-671B, Qwen3-Embedding-8B)
- 💬 Interactive chat interface with conversation history
- 🔄 Automatic endpoint testing and failover
- 🧹 Automatic response cleaning (removes thinking tags and special markers)
- 📝 Full conversation context management
+- ✅ **支援內網和外網連接** - 自動偵測可用的 API 端點
+- 💬 **互動式對話介面** - 像聊天一樣與 AI 對話
+- 🤖 **多模型支援** - GPT-OSS、DeepSeek、Qwen 等多種模型
+- 🔄 **自動重試機制** - 連接失敗時自動切換端點
+- 🧹 **智慧清理回應** - 自動移除 AI 思考過程的標記
+- 📝 **對話歷史管理** - 保持上下文連貫的對話

-## Quick Start
+## 🚀 快速開始

-### Installation
+### 1. 安裝需求
+
+確保你的電腦已安裝 Python 3.7 或更新版本。

 ```bash
-# Clone the repository
-git clone https://github.com/yourusername/llama-api-client.git
-cd llama-api-client
-
-# Install dependencies
-pip install -r requirements.txt
+# 安裝必要套件
+pip install openai
 ```

-### Basic Usage
+### 2. 下載程式
+
+```bash
+# 複製專案
+git clone https://gitea.theaken.com/aken1023/pj_llama.git
+cd pj_llama
+
+# 或直接下載 ZIP 檔案解壓縮
+```
+
+### 3. 執行對話程式
+
+```bash
+# 執行主程式（自動選擇最佳連接）
+python llama_full_api.py
+
+# 或執行內網專用版本
+python llama_chat.py
+```
+
+## 📖 使用說明
+
+### 基本對話
+
+執行程式後，會出現以下畫面：
+
+```
+============================================================
+Llama API 完整對話程式
+時間: 2025-09-19 16:00:00
+============================================================
+
+[內網端點測試]
+  測試 內網端點 1 (21180)... [OK]
+  測試 內網端點 2 (21181)... [OK]
+  測試 內網端點 3 (21182)... [OK]
+
+找到 3 個可用端點，請選擇 (預設: 1): 
+```
+
+選擇端點後即可開始對話：
+
+```
+你: 你好
+AI: 你好！有什麼我可以幫助你的嗎？
+
+你: 1+1等於多少？
+AI: 1+1等於2。
+```
+
+### 對話指令
+
+在對話中可以使用以下指令：
+
+| 指令 | 功能 |
+|-----|------|
+| `exit` 或 `quit` | 結束對話 |
+| `clear` | 清空對話歷史，開始新對話 |
+| `model` | 切換使用的 AI 模型 |
+
+## 🔧 程式檔案說明
+
+| 檔案名稱 | 用途說明 |
+|---------|---------|
+| `llama_full_api.py` | **主程式** - 完整功能版本，支援所有端點 |
+| `llama_chat.py` | 內網專用對話程式 |
+| `quick_test.py` | 快速測試連接是否正常 |
+| `local_api_test.py` | 測試所有端點的工具 |
+
+## 🌐 可用的 API 端點
+
+### 內網端點（公司/學校內部網路）
+
+| 端點 | 地址 | 狀態 |
+|-----|------|------|
+| 端點 1 | `http://192.168.0.6:21180/v1` | ✅ 正常 |
+| 端點 2 | `http://192.168.0.6:21181/v1` | ✅ 正常 |
+| 端點 3 | `http://192.168.0.6:21182/v1` | ✅ 正常 |
+
+### 外網端點（需要網路連接）
+
+| 端點 | 地址 | 狀態 |
+|-----|------|------|
+| 通用端點 | `https://llama.theaken.com/v1` | 📡 需測試 |
+
+## 🤖 支援的 AI 模型
+
+1. **GPT-OSS-120B** - 開源 GPT 模型，1200 億參數
+2. **DeepSeek-R1-671B** - DeepSeek 推理模型，6710 億參數
+3. **Qwen3-Embedding-8B** - 通義千問嵌入模型，80 億參數
+
+## ❓ 常見問題
+
+### 問題：程式顯示「無法連接」
+
+**解決方法：**
+1. 檢查網路連接是否正常
+2. 如果在公司/學校，確認是否在內網環境
+3. 嘗試執行 `python quick_test.py` 測試連接
+
+### 問題：AI 回應包含奇怪的標記
+
+**說明：** 
+有時 AI 回應會包含 `<think>` 或 `<|channel|>` 等標記，這是 AI 的思考過程，程式會自動清理這些內容。
+
+### 問題：對話不連貫
+
+**解決方法：**
+使用 `clear` 指令清空對話歷史，開始新的對話。
+
+## 📝 簡單範例程式碼
+
+如果你想在自己的程式中使用，可以參考以下程式碼：

 ```python
 from openai import OpenAI

-# Configure API
-API_KEY = "paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo="
-BASE_URL = "http://192.168.0.6:21180/v1"
-
-# Create client
-client = OpenAI(api_key=API_KEY, base_url=BASE_URL)
-
-# Send request
-response = client.chat.completions.create(
-    model="gpt-oss-120b",
-    messages=[{"role": "user", "content": "Hello!"}],
-    temperature=0.7,
-    max_tokens=200
+# 設定連接
+client = OpenAI(
+    api_key="paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo=",
+    base_url="http://192.168.0.6:21180/v1"
 )

+# 發送訊息
+response = client.chat.completions.create(
+    model="gpt-oss-120b",
+    messages=[
+        {"role": "user", "content": "你好"}
+    ]
+)
+
+# 顯示回應
 print(response.choices[0].message.content)
 ```

-### Run Interactive Chat
+## 🛠️ 進階設定

-```bash
-# Full-featured chat with all endpoints
-python llama_full_api.py
+### 修改 API 金鑰

-# Internal network only
-python llama_chat.py
+如果需要使用不同的 API 金鑰，編輯程式中的：

-# Quick test
-python quick_test.py
-```
-
-## Available Endpoints
-
-### Internal Network (Tested & Working ✅)
-
-| Endpoint | URL | Status |
-|----------|-----|--------|
-| Internal 1 | `http://192.168.0.6:21180/v1` | ✅ Working |
-| Internal 2 | `http://192.168.0.6:21181/v1` | ✅ Working |
-| Internal 3 | `http://192.168.0.6:21182/v1` | ✅ Working |
-| Internal 4 | `http://192.168.0.6:21183/v1` | ❌ Error 500 |
-
-### External Network
-
-| Endpoint | URL | Status |
-|----------|-----|--------|
-| GPT-OSS | `https://llama.theaken.com/v1/gpt-oss-120b` | 🔄 Pending |
-| DeepSeek | `https://llama.theaken.com/v1/deepseek-r1-671b` | 🔄 Pending |
-| General | `https://llama.theaken.com/v1` | 🔄 Pending |
-
-## Project Structure
-
-```
-llama-api-client/
-├── README.md                 # This file
-├── requirements.txt          # Python dependencies
-├── 操作指南.md               # Chinese operation guide
-├── llama_full_api.py        # Full-featured chat client
-├── llama_chat.py            # Internal network chat client
-├── local_api_test.py        # Endpoint testing tool
-├── quick_test.py            # Quick connection test
-├── test_all_models.py       # Model testing script
-└── demo_chat.py             # Demo chat with fallback
-```
-
-## Chat Commands
-
-During chat sessions, you can use these commands:
-
- `exit` or `quit` - End the conversation
- `clear` - Clear conversation history
- `model` - Switch between available models
-
-## Configuration
-
-### API Key
 ```python
-API_KEY = "paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo="
+API_KEY = "你的新金鑰"
 ```

-### Available Models
- `gpt-oss-120b` - GPT Open Source 120B parameters
- `deepseek-r1-671b` - DeepSeek R1 671B parameters
- `qwen3-embedding-8b` - Qwen3 Embedding 8B parameters
+### 新增端點

-## Troubleshooting
+在 `llama_full_api.py` 中的 `ENDPOINTS` 加入新端點：

-### Issue: 502 Bad Gateway
-**Cause**: External API server is offline  
-**Solution**: Use internal network endpoints
-
-### Issue: Connection Error
-**Cause**: Not on internal network or incorrect IP  
-**Solution**: 
-1. Verify network connectivity: `ping 192.168.0.6`
-2. Check firewall settings
-3. Ensure you're on the same network
-
-### Issue: Encoding Error
-**Cause**: Windows terminal encoding issues  
-**Solution**: Use English for conversations or modify terminal encoding
-
-### Issue: Response Contains Special Markers
-**Description**: Responses may contain `<think>`, `<|channel|>` tags  
-**Solution**: The client automatically removes these markers
-
-## Response Cleaning
-
-The client automatically removes these special markers from AI responses:
- `<think>...</think>` - Thinking process
- `<|channel|>...<|message|>` - Channel markers
- `<|end|>`, `<|start|>` - End/start markers
-
-## Requirements
-
- Python 3.7+
- openai>=1.0.0
- requests (optional, for direct API calls)
-
-## Development
-
-### Testing Connection
 ```python
-python -c "from openai import OpenAI; client = OpenAI(api_key='YOUR_KEY', base_url='YOUR_URL'); print(client.chat.completions.create(model='gpt-oss-120b', messages=[{'role': 'user', 'content': 'test'}], max_tokens=5).choices[0].message.content)"
+"內網": [
+    {
+        "name": "新端點",
+        "url": "http://新的地址/v1",
+        "models": ["gpt-oss-120b"]
+    }
+]
 ```

-### Adding New Endpoints
-Edit `ENDPOINTS` dictionary in `llama_full_api.py`:
-```python
-ENDPOINTS = {
-    "internal": [
-        {
-            "name": "New Endpoint",
-            "url": "http://new-endpoint/v1",
-            "models": ["gpt-oss-120b"]
-        }
-    ]
-}
-```
+## 📄 授權條款

-## License
+本專案採用 MIT 授權條款，可自由使用、修改和分發。

-MIT License - See LICENSE file for details
+## 🤝 問題回報

-## Contributing
+如果遇到問題或有建議，歡迎在 Gitea 上開 Issue：
+https://gitea.theaken.com/aken1023/pj_llama/issues

-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+## 📊 測試狀態

-## Support
-
-For issues or questions:
-1. Check the [操作指南.md](操作指南.md) for detailed Chinese documentation
-2. Open an issue on GitHub
-3. Contact the API administrator for server-related issues
-
-## Acknowledgments
-
- Built with OpenAI Python SDK
- Compatible with OpenAI API format
- Supports multiple Llama model variants
+最後測試時間：2025-09-19
+- ✅ 內網端點 1-3：全部正常
+- ❌ 外網端點：暫時無法使用（502 錯誤）

 ---

-**Last Updated**: 2025-09-19  
-**Version**: 1.0.0  
-**Status**: Internal endpoints working, external endpoints pending
+**版本**: 1.0.0  
+**作者**: Aken  
+**專案網址**: https://gitea.theaken.com/aken1023/pj_llama