diff --git a/README.md b/README.md index b737bd8..d6be2af 100644 --- 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 回應會包含 `` 或 `<|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 ``, `<|channel|>` tags -**Solution**: The client automatically removes these markers - -## Response Cleaning - -The client automatically removes these special markers from AI responses: -- `...` - 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 \ No newline at end of file +**版本**: 1.0.0 +**作者**: Aken +**專案網址**: https://gitea.theaken.com/aken1023/pj_llama \ No newline at end of file