更新 README.md 為中文版本
- 改為簡單易懂的中文說明 - 加入詳細的使用教學 - 增加常見問題解答 - 提供範例程式碼 - 加入 emoji 讓內容更生動
This commit is contained in:
330
README.md
330
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
|
- ✅ **支援內網和外網連接** - 自動偵測可用的 API 端點
|
||||||
- 🤖 Multiple model support (GPT-OSS-120B, DeepSeek-R1-671B, Qwen3-Embedding-8B)
|
- 💬 **互動式對話介面** - 像聊天一樣與 AI 對話
|
||||||
- 💬 Interactive chat interface with conversation history
|
- 🤖 **多模型支援** - GPT-OSS、DeepSeek、Qwen 等多種模型
|
||||||
- 🔄 Automatic endpoint testing and failover
|
- 🔄 **自動重試機制** - 連接失敗時自動切換端點
|
||||||
- 🧹 Automatic response cleaning (removes thinking tags and special markers)
|
- 🧹 **智慧清理回應** - 自動移除 AI 思考過程的標記
|
||||||
- 📝 Full conversation context management
|
- 📝 **對話歷史管理** - 保持上下文連貫的對話
|
||||||
|
|
||||||
## Quick Start
|
## 🚀 快速開始
|
||||||
|
|
||||||
### Installation
|
### 1. 安裝需求
|
||||||
|
|
||||||
|
確保你的電腦已安裝 Python 3.7 或更新版本。
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Clone the repository
|
# 安裝必要套件
|
||||||
git clone https://github.com/yourusername/llama-api-client.git
|
pip install openai
|
||||||
cd llama-api-client
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
```python
|
||||||
from openai import OpenAI
|
from openai import OpenAI
|
||||||
|
|
||||||
# Configure API
|
# 設定連接
|
||||||
API_KEY = "paVrIT+XU1NhwCAOb0X4aYi75QKogK5YNMGvQF1dCyo="
|
client = OpenAI(
|
||||||
BASE_URL = "http://192.168.0.6:21180/v1"
|
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
|
|
||||||
)
|
)
|
||||||
|
|
||||||
|
# 發送訊息
|
||||||
|
response = client.chat.completions.create(
|
||||||
|
model="gpt-oss-120b",
|
||||||
|
messages=[
|
||||||
|
{"role": "user", "content": "你好"}
|
||||||
|
]
|
||||||
|
)
|
||||||
|
|
||||||
|
# 顯示回應
|
||||||
print(response.choices[0].message.content)
|
print(response.choices[0].message.content)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Run Interactive Chat
|
## 🛠️ 進階設定
|
||||||
|
|
||||||
```bash
|
### 修改 API 金鑰
|
||||||
# Full-featured chat with all endpoints
|
|
||||||
python llama_full_api.py
|
|
||||||
|
|
||||||
# Internal network only
|
如果需要使用不同的 API 金鑰，編輯程式中的：
|
||||||
python llama_chat.py
|
|
||||||
|
|
||||||
# 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
|
```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
|
||||||
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
|
最後測試時間：2025-09-19
|
||||||
|
- ✅ 內網端點 1-3：全部正常
|
||||||
For issues or questions:
|
- ❌ 外網端點：暫時無法使用（502 錯誤）
|
||||||
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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Last Updated**: 2025-09-19
|
**版本**: 1.0.0
|
||||||
**Version**: 1.0.0
|
**作者**: Aken
|
||||||
**Status**: Internal endpoints working, external endpoints pending
|
**專案網址**: https://gitea.theaken.com/aken1023/pj_llama
|
||||||
Reference in New Issue
Block a user