mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-08-03 19:12:04 +08:00
docs: restructure user manual for i18n and add EN/JA translations
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
This commit is contained in:
Jason
@@ -0,0 +1,222 @@
|
||||
# 4.1 Proxy Service
|
||||
|
||||
## Overview
|
||||
|
||||
The proxy service starts a local HTTP proxy through which all API requests are forwarded.
|
||||
|
||||
**Primary uses**:
|
||||
- Record request logs
|
||||
- Track API usage
|
||||
- Support failover
|
||||
- Centrally manage requests from multiple applications
|
||||
|
||||
## Start the Proxy
|
||||
|
||||
### Option 1: Main Interface Toggle
|
||||
|
||||
Click the **Proxy Toggle** button at the top of the main interface.
|
||||
|
||||
Toggle states:
|
||||
- White: Proxy not running
|
||||
- Green: Proxy running
|
||||
|
||||
|
||||
|
||||
### Option 2: Settings Page
|
||||
|
||||
1. Open "Settings > Advanced > Proxy Service"
|
||||
2. Click the toggle in the top-right corner
|
||||
|
||||
|
||||
|
||||
## Proxy Configuration
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
| Setting | Description | Default |
|
||||
|---------|-------------|---------|
|
||||
| Listen Address | IP address the proxy binds to | `127.0.0.1` |
|
||||
| Listen Port | Port the proxy listens on | `15721` |
|
||||
| Enable Logging | Whether to record request logs | Enabled |
|
||||
|
||||
### Modify Configuration
|
||||
|
||||
1. **Stop the proxy service** (must stop first)
|
||||
2. Modify the listen address or port
|
||||
3. Click "Save"
|
||||
4. Restart the proxy
|
||||
|
||||
> Modifying address/port requires stopping the proxy service first
|
||||
|
||||
### Listen Address Options
|
||||
|
||||
| Address | Description |
|
||||
|---------|-------------|
|
||||
| `127.0.0.1` | Only accessible from local machine (recommended) |
|
||||
| `0.0.0.0` | Allow LAN access |
|
||||
|
||||
## Running Status
|
||||
|
||||
When the proxy is running, the panel displays the following information:
|
||||
|
||||
### Service Address
|
||||
|
||||
```
|
||||
http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
Click the "Copy" button to copy the address.
|
||||
|
||||
### Current Providers
|
||||
|
||||
Displays the currently used provider for each app:
|
||||
|
||||
```
|
||||
Claude: PackyCode
|
||||
Codex: AIGoCode
|
||||
Gemini: Google Official
|
||||
```
|
||||
|
||||
### Statistics
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| Active Connections | Number of requests currently being processed |
|
||||
| Total Requests | Total number of requests since startup |
|
||||
| Success Rate | Percentage of successful requests (>90% green, <=90% yellow) |
|
||||
| Uptime | How long the proxy has been running |
|
||||
|
||||
### Failover Queue
|
||||
|
||||
The proxy panel displays the failover queue by app type:
|
||||
|
||||
```
|
||||
Claude
|
||||
├── 1. PackyCode [Currently Using] ●
|
||||
├── 2. AIGoCode ●
|
||||
└── 3. Backup Provider ○
|
||||
|
||||
Codex
|
||||
├── 1. AIGoCode [Currently Using] ●
|
||||
└── 2. Backup Provider ●
|
||||
```
|
||||
|
||||
Queue details:
|
||||
- Numbers indicate priority order
|
||||
- "Currently Using" label indicates the active provider
|
||||
- Health badges show provider status:
|
||||
- Green: Healthy (0 consecutive failures)
|
||||
- Yellow: Degraded (1-2 consecutive failures)
|
||||
- Red: Unhealthy (3+ consecutive failures)
|
||||
|
||||
## How It Works
|
||||
|
||||
### Request Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as CLI Tool (Claude)
|
||||
participant Proxy as Local Proxy (CC Switch)
|
||||
participant API as API Provider (Anthropic)
|
||||
participant DB as Data Store (Logger)
|
||||
|
||||
CLI->>Proxy: Send API request
|
||||
Proxy->>DB: Record request log / track usage
|
||||
Proxy->>API: Forward request
|
||||
API-->>Proxy: Return response
|
||||
Proxy-->>CLI: Return response
|
||||
```
|
||||
|
||||
### Configuration Changes
|
||||
|
||||
After starting the proxy and enabling app takeover, CC Switch modifies app configurations:
|
||||
|
||||
**Claude**:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex**:
|
||||
```toml
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini**:
|
||||
```
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
## Stop the Proxy
|
||||
|
||||
### Option 1: Main Interface Toggle
|
||||
|
||||
Click the proxy toggle button to turn it off.
|
||||
|
||||
### Option 2: Settings Page
|
||||
|
||||
Turn off the toggle in the proxy service panel.
|
||||
|
||||
### Post-stop Processing
|
||||
|
||||
When stopping the proxy, CC Switch will:
|
||||
|
||||
1. Restore app configurations to their original state
|
||||
2. Save request logs
|
||||
3. Close all connections
|
||||
|
||||
## Log Recording
|
||||
|
||||
### Enable Logging
|
||||
|
||||
Enable the "Enable Logging" toggle in the proxy panel.
|
||||
|
||||
### Log Contents
|
||||
|
||||
Each request record includes:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Time | Request time |
|
||||
| App | Claude / Codex / Gemini |
|
||||
| Provider | Provider used |
|
||||
| Model | Requested model |
|
||||
| Tokens | Input/output token count |
|
||||
| Latency | Request duration |
|
||||
| Status | Success/failure |
|
||||
|
||||
### View Logs
|
||||
|
||||
View request logs in the "Settings > Usage" tab.
|
||||
|
||||
## FAQ
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
Error message: `Address already in use`
|
||||
|
||||
Solution:
|
||||
1. Change the port (e.g., to 5001)
|
||||
2. Or close the program occupying the port
|
||||
|
||||
### Proxy Fails to Start
|
||||
|
||||
Check:
|
||||
- Is the port occupied
|
||||
- Are there sufficient permissions
|
||||
- Is the firewall blocking it
|
||||
|
||||
### Request Timeout
|
||||
|
||||
Possible causes:
|
||||
- Network issues
|
||||
- Provider server issues
|
||||
- Incorrect proxy configuration
|
||||
|
||||
Solutions:
|
||||
- Check network connection
|
||||
- Try accessing the provider API directly
|
||||
- Check provider configuration
|
||||
@@ -0,0 +1,195 @@
|
||||
# 4.2 App Takeover
|
||||
|
||||
## Overview
|
||||
|
||||
App takeover means letting CC Switch's proxy intercept and forward a specific application's API requests.
|
||||
|
||||
When takeover is enabled:
|
||||
- The app's API requests are forwarded through the local proxy
|
||||
- Request logs and usage statistics can be recorded
|
||||
- Failover functionality becomes available
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The proxy service must be started before using the app takeover feature.
|
||||
|
||||
## Enable Takeover
|
||||
|
||||
### Location
|
||||
|
||||
Settings > Advanced > Proxy Service > App Takeover area
|
||||
|
||||
### Steps
|
||||
|
||||
1. Ensure the proxy service is started
|
||||
2. Find the "App Takeover" area
|
||||
3. Enable the toggle for the desired apps
|
||||
|
||||
### Takeover Toggles
|
||||
|
||||
| Toggle | Effect |
|
||||
|--------|--------|
|
||||
| Claude Takeover | Intercept Claude Code requests |
|
||||
| Codex Takeover | Intercept Codex requests |
|
||||
| Gemini Takeover | Intercept Gemini CLI requests |
|
||||
|
||||
Multiple app takeovers can be enabled simultaneously.
|
||||
|
||||
## How Takeover Works
|
||||
|
||||
### Configuration Changes
|
||||
|
||||
When takeover is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local proxy.
|
||||
|
||||
**Claude configuration change**:
|
||||
|
||||
```json
|
||||
// Before takeover
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
}
|
||||
}
|
||||
|
||||
// After takeover
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex configuration change**:
|
||||
|
||||
```toml
|
||||
# Before takeover
|
||||
base_url = "https://api.openai.com/v1"
|
||||
|
||||
# After takeover
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini configuration change**:
|
||||
|
||||
```bash
|
||||
# Before takeover
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
|
||||
# After takeover
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
### Request Forwarding
|
||||
|
||||
When the proxy receives a request:
|
||||
|
||||
1. Identifies the request source (Claude/Codex/Gemini)
|
||||
2. Looks up the currently enabled provider for that app
|
||||
3. Forwards the request to the provider's actual endpoint
|
||||
4. Records the request log
|
||||
5. Returns the response to the app
|
||||
|
||||
## Takeover Status Indicators
|
||||
|
||||
### Main Interface Indicators
|
||||
|
||||
When takeover is enabled, the main interface shows the following changes:
|
||||
|
||||
- **Proxy logo color**: Changes from colorless to green
|
||||
- **Provider cards**: The currently active provider shows a green border
|
||||
|
||||
### Provider Card States
|
||||
|
||||
| State | Border Color | Description |
|
||||
|-------|--------------|-------------|
|
||||
| Currently Active | Blue | Provider in the config file (non-proxy mode) |
|
||||
| Proxy Active | Green | Provider actually used by the proxy |
|
||||
| Normal | Default | Unused provider |
|
||||
|
||||
## Disable Takeover
|
||||
|
||||
### Steps
|
||||
|
||||
1. Turn off the corresponding app's takeover toggle in the proxy panel
|
||||
2. Or directly stop the proxy service
|
||||
|
||||
### Configuration Restoration
|
||||
|
||||
When disabling takeover, CC Switch will:
|
||||
|
||||
1. Restore the app configuration to its pre-takeover state
|
||||
2. Save current request logs
|
||||
|
||||
## Takeover and Provider Switching
|
||||
|
||||
### Switching Providers in Takeover Mode
|
||||
|
||||
When switching providers in takeover mode:
|
||||
|
||||
1. Click the "Enable" button on a provider in the main interface
|
||||
2. The proxy immediately uses the new provider to forward requests
|
||||
3. **No need to restart the CLI tool**
|
||||
|
||||
This is a major advantage of takeover mode: provider switching takes effect instantly.
|
||||
|
||||
### Switching Without Takeover
|
||||
|
||||
When switching providers without takeover:
|
||||
|
||||
1. Configuration file is modified
|
||||
2. CLI tool must be restarted for changes to take effect
|
||||
|
||||
## Multi-app Takeover
|
||||
|
||||
Multiple apps can be taken over simultaneously, each managed independently:
|
||||
|
||||
- Independent provider configurations
|
||||
- Independent failover queues
|
||||
- Independent request statistics
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Scenario 1: Usage Monitoring
|
||||
|
||||
Enable takeover + log recording to monitor API usage.
|
||||
|
||||
### Scenario 2: Quick Switching
|
||||
|
||||
With takeover enabled, switching providers does not require restarting CLI tools.
|
||||
|
||||
### Scenario 3: Failover
|
||||
|
||||
Enabling takeover is a prerequisite for using the failover feature.
|
||||
|
||||
## Notes
|
||||
|
||||
### Performance Impact
|
||||
|
||||
The proxy adds minimal latency (typically < 10ms), negligible for most scenarios.
|
||||
|
||||
### Network Requirements
|
||||
|
||||
In takeover mode, CLI tools must be able to access the local proxy address.
|
||||
|
||||
### Configuration Backup
|
||||
|
||||
Before enabling takeover, CC Switch backs up the original configuration and restores it when disabled.
|
||||
|
||||
## FAQ
|
||||
|
||||
### Requests Fail After Takeover
|
||||
|
||||
Check:
|
||||
- Is the proxy service running normally
|
||||
- Is the provider configuration correct
|
||||
- Is the network working properly
|
||||
|
||||
### Configuration Not Restored After Disabling Takeover
|
||||
|
||||
Possible causes:
|
||||
- Proxy exited abnormally
|
||||
- Configuration file was modified by another program
|
||||
|
||||
Solutions:
|
||||
- Manually edit the provider and re-save
|
||||
- Or re-enable and then disable takeover
|
||||
@@ -0,0 +1,232 @@
|
||||
# 4.3 Failover
|
||||
|
||||
## Overview
|
||||
|
||||
The failover feature automatically switches to a backup provider when the primary provider's request fails, ensuring uninterrupted service.
|
||||
|
||||
**Applicable scenarios**:
|
||||
- Unstable provider services
|
||||
- High availability requirements
|
||||
- Long-running tasks
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Using the failover feature requires:
|
||||
|
||||
1. Proxy service started
|
||||
2. App takeover enabled
|
||||
3. Failover queue configured
|
||||
4. Auto failover enabled
|
||||
|
||||
## Configure the Failover Queue
|
||||
|
||||
### Open Configuration Page
|
||||
|
||||
Settings > Advanced > Failover
|
||||
|
||||
### Select Application
|
||||
|
||||
Three tabs at the top of the page:
|
||||
- Claude
|
||||
- Codex
|
||||
- Gemini
|
||||
|
||||
Select the application to configure.
|
||||
|
||||
### Add Backup Providers
|
||||
|
||||
1. In the "Failover Queue" area
|
||||
2. Click "Add Provider"
|
||||
3. Select a provider from the dropdown list
|
||||
4. The provider is added to the end of the queue
|
||||
|
||||
### Adjust Priority
|
||||
|
||||
Drag providers to adjust their order:
|
||||
- Lower numbers mean higher priority
|
||||
- After the primary provider fails, backup providers are tried in order
|
||||
|
||||
### Remove Provider
|
||||
|
||||
Click the "Remove" button to the right of the provider.
|
||||
|
||||
## Main Interface Quick Actions
|
||||
|
||||
When both proxy and failover are enabled, provider cards display a failover toggle.
|
||||
|
||||
### Add to Queue
|
||||
|
||||
1. Find the provider card
|
||||
2. Enable the failover toggle
|
||||
3. The provider is automatically added to the queue
|
||||
|
||||
### Remove from Queue
|
||||
|
||||
1. Disable the failover toggle on the provider card
|
||||
2. The provider is removed from the queue
|
||||
|
||||
## Enable Auto Failover
|
||||
|
||||
### Steps
|
||||
|
||||
1. On the failover configuration page
|
||||
2. Enable the "Auto Failover" toggle
|
||||
|
||||
### Toggle Description
|
||||
|
||||
| State | Behavior |
|
||||
|-------|----------|
|
||||
| Off | Only records failures, no automatic switching |
|
||||
| On | Automatically switches to the next provider on failure |
|
||||
|
||||
## Failover Flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start[Request arrives at proxy] --> Send[Send to current provider]
|
||||
Send --> CheckSuccess{Success?}
|
||||
CheckSuccess -- Yes --> Return[Return response]
|
||||
CheckSuccess -- No --> LogFail[Record failure]
|
||||
LogFail --> CheckCircuit{Check circuit breaker}
|
||||
CheckCircuit -- Tripped --> Skip[Skip this provider]
|
||||
CheckCircuit -- Not tripped --> IncFail[Increment failure count]
|
||||
Skip --> Next{Next in queue?}
|
||||
IncFail --> Next
|
||||
Next -- Yes --> Switch[Switch provider]
|
||||
Switch --> Retry[Retry request]
|
||||
Retry --> Send
|
||||
Next -- No --> Error[Return error]
|
||||
```
|
||||
|
||||
## Circuit Breaker Configuration
|
||||
|
||||
The circuit breaker prevents frequent retries against failing providers.
|
||||
|
||||
### Configuration Items
|
||||
|
||||
Different apps have independent default configurations. Below are general defaults; Claude has its own relaxed configuration.
|
||||
|
||||
| Setting | Description | General Default | Claude Default | Range |
|
||||
|---------|-------------|-----------------|----------------|-------|
|
||||
| Failure Threshold | Consecutive failures to trigger circuit breaker | 4 | 8 | 1-20 |
|
||||
| Recovery Success Threshold | Successes needed in half-open state to close breaker | 2 | 3 | 1-10 |
|
||||
| Recovery Wait Time | Time before attempting recovery after tripping (seconds) | 60 | 90 | 0-300 |
|
||||
| Error Rate Threshold | Error rate that opens the circuit breaker | 60% | 70% | 0-100% |
|
||||
| Minimum Requests | Minimum requests before calculating error rate | 10 | 15 | 5-100 |
|
||||
|
||||
> Claude has more relaxed default settings due to longer request times, tolerating more failures.
|
||||
|
||||
### Timeout Configuration
|
||||
|
||||
| Setting | Description | General Default | Claude Default | Range |
|
||||
|---------|-------------|-----------------|----------------|-------|
|
||||
| Stream First Byte Timeout | Max wait time for first data chunk (seconds) | 60 | 90 | 1-120 |
|
||||
| Stream Idle Timeout | Max interval between data chunks (seconds) | 120 | 180 | 60-600 (0 to disable) |
|
||||
| Non-stream Timeout | Total timeout for non-streaming requests (seconds) | 600 | 600 | 60-1200 |
|
||||
|
||||
### Retry Configuration
|
||||
|
||||
| Setting | Description | General Default | Claude Default | Range |
|
||||
|---------|-------------|-----------------|----------------|-------|
|
||||
| Max Retries | Number of retries on request failure | 3 | 6 | 0-10 |
|
||||
|
||||
> Gemini's default max retries is 5.
|
||||
|
||||
### Circuit Breaker States
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| Closed | Normal state, requests allowed |
|
||||
| Open | Circuit broken, this provider is skipped |
|
||||
| Half-Open | Attempting recovery, sending probe requests |
|
||||
|
||||
### State Transitions
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Closed: Initialize
|
||||
Closed --> Open: Failures >= threshold
|
||||
Open --> HalfOpen: Recovery wait time expires
|
||||
HalfOpen --> Closed: Probe successes >= recovery threshold
|
||||
HalfOpen --> Open: Probe failed
|
||||
```
|
||||
|
||||
## Health Status Indicators
|
||||
|
||||
### Provider Cards
|
||||
|
||||
Cards display health status badges:
|
||||
|
||||
| Badge | Status | Description |
|
||||
|-------|--------|-------------|
|
||||
| Green | Healthy | 0 consecutive failures |
|
||||
| Yellow | Warning | Has failures but circuit not tripped |
|
||||
| Red | Circuit Broken | Circuit breaker tripped, temporarily skipped |
|
||||
|
||||
### Queue List
|
||||
|
||||
The failover queue also displays each provider's health status.
|
||||
|
||||
## Failover Logs
|
||||
|
||||
Each failover event records:
|
||||
|
||||
| Information | Description |
|
||||
|-------------|-------------|
|
||||
| Time | When it occurred |
|
||||
| Original Provider | The provider that failed |
|
||||
| New Provider | The provider switched to |
|
||||
| Failure Reason | Error message |
|
||||
|
||||
Viewable in the request logs within usage statistics.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Queue Configuration Recommendations
|
||||
|
||||
1. **Primary provider**: The most stable and fastest provider
|
||||
2. **First backup**: Second-best choice
|
||||
3. **Second backup**: Last resort
|
||||
|
||||
### Circuit Breaker Configuration Recommendations
|
||||
|
||||
| Scenario | Failure Threshold | Recovery Wait |
|
||||
|----------|-------------------|---------------|
|
||||
| High availability requirement | 2 | 30 seconds |
|
||||
| General scenario | 3 | 60 seconds |
|
||||
| Tolerant of occasional failures | 5 | 120 seconds |
|
||||
|
||||
### Monitoring Recommendations
|
||||
|
||||
Periodically check:
|
||||
- Health status of each provider
|
||||
- Failover frequency
|
||||
- Circuit breaker trigger frequency
|
||||
|
||||
## FAQ
|
||||
|
||||
### Failover Not Triggering
|
||||
|
||||
Check:
|
||||
1. Is the proxy service running
|
||||
2. Is app takeover enabled
|
||||
3. Is auto failover enabled
|
||||
4. Are there backup providers in the queue
|
||||
|
||||
### Failover Triggering Too Frequently
|
||||
|
||||
Possible causes:
|
||||
- Unstable primary provider
|
||||
- Network issues
|
||||
- Configuration errors
|
||||
|
||||
Solutions:
|
||||
- Check primary provider status
|
||||
- Adjust circuit breaker parameters
|
||||
- Consider changing the primary provider
|
||||
|
||||
### All Providers Circuit-Broken
|
||||
|
||||
Wait for the recovery wait time to expire for automatic recovery, or:
|
||||
1. Manually restart the proxy service
|
||||
2. Reset circuit breaker states
|
||||
@@ -0,0 +1,291 @@
|
||||
# 4.4 Usage Statistics
|
||||
|
||||
## Overview
|
||||
|
||||
The usage statistics feature records and analyzes API request data, helping you:
|
||||
|
||||
- Understand API usage patterns
|
||||
- Estimate cost expenditure
|
||||
- Analyze usage patterns
|
||||
- Troubleshoot issues
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Using the usage statistics feature requires:
|
||||
|
||||
1. Proxy service started
|
||||
2. App takeover enabled
|
||||
3. Log recording enabled
|
||||
|
||||
## Open Usage Statistics
|
||||
|
||||
Settings > Usage Tab
|
||||
|
||||
## Statistics Overview
|
||||
|
||||
### Summary Cards
|
||||
|
||||
Key metrics displayed at the top of the page:
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| Total Requests | Total number of requests in the time period |
|
||||
| Total Tokens | Total input + output tokens |
|
||||
| Estimated Cost | Cost calculated based on pricing configuration |
|
||||
| Success Rate | Percentage of successful requests |
|
||||
|
||||
### Time Range
|
||||
|
||||
Select the time range for statistics:
|
||||
|
||||
| Option | Range |
|
||||
|--------|-------|
|
||||
| Today | From 00:00 today to now |
|
||||
| Last 7 Days | Past 7 days |
|
||||
| Last 30 Days | Past 30 days |
|
||||
|
||||
|
||||
|
||||
## Trend Charts
|
||||
|
||||
### Request Trend
|
||||
|
||||
Line chart showing the trend of request counts:
|
||||
|
||||
- X-axis: Time
|
||||
- Y-axis: Request count
|
||||
- Viewable by hour/day
|
||||
- Supports zoom and drag
|
||||
|
||||
### Token Trend
|
||||
|
||||
Shows token usage trends:
|
||||
|
||||
- Input Tokens (blue) - Prompt content sent by the user
|
||||
- Output Tokens (green) - Response content generated by AI
|
||||
- Cache Creation Tokens (orange) - Tokens consumed when first creating cache
|
||||
- Cache Hit Tokens (purple) - Tokens saved by reusing cache
|
||||
- Cost (red dashed line, right Y-axis) - Estimated cost
|
||||
|
||||
> **Cache Token explanation**: Anthropic API supports Prompt Caching. Creating cache incurs a higher fee (typically 1.25x input price), but subsequent cache hits only charge 0.1x, significantly reducing costs for repeated requests.
|
||||
|
||||
### Time Granularity
|
||||
|
||||
- **Today**: Displayed by hour (24 data points)
|
||||
- **7 Days/30 Days**: Displayed by day
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Detailed Data
|
||||
|
||||
Three data tabs at the bottom of the page:
|
||||
|
||||
### Request Logs
|
||||
|
||||
Detailed record of each request:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Time | Request time |
|
||||
| Provider | Provider name used |
|
||||
| Model | Requested model (billing model) |
|
||||
| Input Tokens | Number of input tokens |
|
||||
| Output Tokens | Number of output tokens |
|
||||
| Cache Read | Cache hit token count |
|
||||
| Cache Creation | Cache creation token count |
|
||||
| Total Cost | Estimated cost (USD) |
|
||||
| Timing Info | Request duration, time to first token, streaming/non-streaming |
|
||||
| Status | HTTP status code |
|
||||
|
||||
#### Timing Information
|
||||
|
||||
The timing info column displays multiple badges:
|
||||
|
||||
| Badge | Description | Color Rules |
|
||||
|-------|-------------|-------------|
|
||||
| Total Duration | Total request time (seconds) | <=5s green, <=120s orange, >120s red |
|
||||
| First Token | Time to first token in streaming requests | <=5s green, <=120s orange, >120s red |
|
||||
| Stream/Non-stream | Request type | Streaming blue, non-streaming purple |
|
||||
|
||||
#### View Details
|
||||
|
||||
Click a request row to view detailed information:
|
||||
|
||||
- Complete request parameters
|
||||
- Response content summary
|
||||
- Error messages (if failed)
|
||||
|
||||
#### Filter Logs
|
||||
|
||||
Supports filtering by the following criteria:
|
||||
|
||||
| Filter | Options |
|
||||
|--------|---------|
|
||||
| App Type | All / Claude / Codex / Gemini |
|
||||
| Status Code | All / 200 / 400 / 401 / 429 / 500 |
|
||||
| Provider | Text search |
|
||||
| Model | Text search |
|
||||
| Time Range | Start time - End time (datetime picker) |
|
||||
|
||||
Action buttons:
|
||||
- **Search**: Apply filter criteria
|
||||
- **Reset**: Restore defaults (past 24 hours)
|
||||
- **Refresh**: Reload data
|
||||
|
||||
|
||||
|
||||
### Provider Statistics
|
||||
|
||||
Statistics grouped by provider:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Provider | Provider name |
|
||||
| Requests | Total requests for this provider |
|
||||
| Successes | Number of successful requests |
|
||||
| Failures | Number of failed requests |
|
||||
| Success Rate | Success percentage |
|
||||
| Total Tokens | Total token usage |
|
||||
| Estimated Cost | Cost for this provider |
|
||||
|
||||
|
||||
|
||||
### Model Statistics
|
||||
|
||||
Statistics grouped by model:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Model | Model name |
|
||||
| Requests | Total requests for this model |
|
||||
| Input Tokens | Total input tokens |
|
||||
| Output Tokens | Total output tokens |
|
||||
| Avg Latency | Average response time |
|
||||
| Estimated Cost | Cost for this model |
|
||||
|
||||
|
||||
|
||||
## Pricing Configuration
|
||||
|
||||
### Open Pricing Configuration
|
||||
|
||||
Settings > Advanced > Pricing Configuration
|
||||
|
||||
### Configure Model Prices
|
||||
|
||||
Set prices for each model (per million tokens):
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Model ID | Model identifier (e.g., claude-3-sonnet) |
|
||||
| Display Name | Custom display name |
|
||||
| Input Price | Price per million input tokens |
|
||||
| Output Price | Price per million output tokens |
|
||||
| Cache Read Price | Price per million cache hit tokens |
|
||||
| Cache Creation Price | Price per million cache creation tokens |
|
||||
|
||||
### Operations
|
||||
|
||||
- **Add**: Click the "Add" button to add model pricing
|
||||
- **Edit**: Click the edit icon at the end of the row to modify
|
||||
- **Delete**: Click the delete icon at the end of the row to remove
|
||||
|
||||
|
||||
|
||||
### Preset Prices
|
||||
|
||||
CC Switch includes preset official prices for common models (per million tokens):
|
||||
|
||||
**Claude Series (USD)**:
|
||||
|
||||
| Model | Input | Output | Cache Read | Cache Creation |
|
||||
|-------|-------|--------|------------|----------------|
|
||||
| **Claude 4.5 Series** | | | | |
|
||||
| claude-opus-4-5 | $5 | $25 | $0.50 | $6.25 |
|
||||
| claude-sonnet-4-5 | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |
|
||||
| **Claude 4 Series** | | | | |
|
||||
| claude-opus-4 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-opus-4-1 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-sonnet-4 | $3 | $15 | $0.30 | $3.75 |
|
||||
| **Claude 3.5 Series** | | | | |
|
||||
| claude-3-5-sonnet | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-3-5-haiku | $0.80 | $4 | $0.08 | $1.00 |
|
||||
|
||||
**OpenAI Series / Codex (USD)**:
|
||||
|
||||
| Model | Input | Output | Cache Read |
|
||||
|-------|-------|--------|------------|
|
||||
| **GPT-5.2 Series** | | | |
|
||||
| gpt-5.2 | $1.75 | $14 | $0.175 |
|
||||
| **GPT-5.1 Series** | | | |
|
||||
| gpt-5.1 | $1.25 | $10 | $0.125 |
|
||||
| **GPT-5 Series** | | | |
|
||||
| gpt-5 | $1.25 | $10 | $0.125 |
|
||||
|
||||
> Note: Codex presets include low/medium/high variants with prices identical to the base model.
|
||||
|
||||
**Gemini Series (USD)**:
|
||||
|
||||
| Model | Input | Output | Cache Read |
|
||||
|-------|-------|--------|------------|
|
||||
| **Gemini 3 Series** | | | |
|
||||
| gemini-3-pro-preview | $2 | $12 | $0.20 |
|
||||
| gemini-3-flash-preview | $0.50 | $3 | $0.05 |
|
||||
| **Gemini 2.5 Series** | | | |
|
||||
| gemini-2.5-pro | $1.25 | $10 | $0.125 |
|
||||
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
|
||||
|
||||
**Chinese Provider Models (CNY)**:
|
||||
|
||||
| Model | Input | Output | Cache Read |
|
||||
|-------|-------|--------|------------|
|
||||
| **DeepSeek** | | | |
|
||||
| deepseek-v3.2 | ¥2.00 | ¥3.00 | ¥0.40 |
|
||||
| deepseek-v3.1 | ¥4.00 | ¥12.00 | ¥0.80 |
|
||||
| deepseek-v3 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| **Kimi (Moonshot)** | | | |
|
||||
| kimi-k2-thinking | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2 | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2-turbo | ¥8.00 | ¥58.00 | ¥1.00 |
|
||||
| **MiniMax** | | | |
|
||||
| minimax-m2.1 | ¥2.10 | ¥8.40 | ¥0.21 |
|
||||
| minimax-m2.1-lightning | ¥2.10 | ¥16.80 | ¥0.21 |
|
||||
| **Others** | | | |
|
||||
| glm-4.7 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| doubao-seed-code | ¥1.20 | ¥8.00 | ¥0.24 |
|
||||
| mimo-v2-flash | Free | Free | - |
|
||||
|
||||
### Custom Prices
|
||||
|
||||
If using proxy services, prices may differ:
|
||||
|
||||
1. Click the "Edit" button
|
||||
2. Modify prices
|
||||
3. Save
|
||||
|
||||
## FAQ
|
||||
|
||||
### Statistics Data Is Empty
|
||||
|
||||
Check:
|
||||
- Is the proxy service running
|
||||
- Is app takeover enabled
|
||||
- Is log recording enabled
|
||||
- Have requests been going through the proxy
|
||||
|
||||
### Cost Estimates Are Inaccurate
|
||||
|
||||
Possible causes:
|
||||
- Pricing configuration doesn't match actual prices
|
||||
- Using a proxy service with special pricing
|
||||
|
||||
Solutions:
|
||||
- Update pricing configuration
|
||||
- Refer to the provider's actual invoices
|
||||
|
||||
### Token Count Differs from Provider
|
||||
|
||||
CC Switch uses its own method to estimate token counts, which may slightly differ from the provider's calculation. Refer to the provider's invoice for authoritative numbers.
|
||||
@@ -0,0 +1,156 @@
|
||||
# 4.5 Model Test
|
||||
|
||||
## Overview
|
||||
|
||||
The model test feature verifies whether a provider's configured model is available by sending actual API requests to test:
|
||||
|
||||
- Whether the model exists
|
||||
- Whether the API Key is valid
|
||||
- Whether the endpoint responds normally
|
||||
- Whether the response latency is acceptable
|
||||
|
||||
## Open Configuration
|
||||
|
||||
Settings > Advanced > Model Test Config
|
||||
|
||||
## Test Model Configuration
|
||||
|
||||
Configure the model used for testing per application:
|
||||
|
||||
| Application | Setting | Default | Notes |
|
||||
|-------------|---------|---------|-------|
|
||||
| Claude | Claude Model | System default | Recommend using Haiku series (low cost, fast) |
|
||||
| Codex | Codex Model | System default | Recommend using mini series |
|
||||
| Gemini | Gemini Model | System default | Recommend using Flash series |
|
||||
|
||||
### Model Selection Tips
|
||||
|
||||
When choosing a test model, consider:
|
||||
|
||||
1. **Cost**: Choose lower-priced models (e.g., Haiku, Mini, Flash)
|
||||
2. **Speed**: Choose fast-responding models
|
||||
3. **Availability**: Choose models supported by the provider
|
||||
|
||||
## Test Parameter Configuration
|
||||
|
||||
### Timeout
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| Timeout | Single request timeout | 45 seconds | 10-120 seconds |
|
||||
|
||||
Setting it too short may cause false negatives; too long delays fault detection.
|
||||
|
||||
### Retries
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| Max Retries | Retries after failure | 2 times | 0-5 times |
|
||||
|
||||
Increase retries when the network is unstable.
|
||||
|
||||
### Degradation Threshold
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| Degradation Threshold | Responses exceeding this time are marked as degraded | 6000ms | 1000-30000ms |
|
||||
|
||||
Providers exceeding the threshold are marked as "degraded" but remain usable.
|
||||
|
||||
## Execute Model Test
|
||||
|
||||
### Manual Test
|
||||
|
||||
Click the "Test" button on the provider card:
|
||||
|
||||
1. Sends a test request to the configured endpoint
|
||||
2. Uses the configured test model
|
||||
3. Waits for response or timeout
|
||||
4. Displays the test result
|
||||
|
||||
### Test Content
|
||||
|
||||
The test request:
|
||||
- Sends a short prompt (e.g., "Hi")
|
||||
- Limits maximum output tokens (typically 10-50)
|
||||
- Uses streaming response to detect time to first byte
|
||||
|
||||
## Test Results
|
||||
|
||||
### Health Status
|
||||
|
||||
| Status | Icon | Description |
|
||||
|--------|------|-------------|
|
||||
| Healthy | Green | Normal response, latency within threshold |
|
||||
| Degraded | Yellow | Normal response, but latency exceeds threshold |
|
||||
| Unavailable | Red | Request failed or timed out |
|
||||
|
||||
### Result Information
|
||||
|
||||
After testing completes, displays:
|
||||
- Response latency (milliseconds)
|
||||
- Time to first byte (TTFB)
|
||||
- Error message (if failed)
|
||||
|
||||
## Integration with Failover
|
||||
|
||||
Model testing works in conjunction with the failover feature:
|
||||
|
||||
### Health Checks
|
||||
|
||||
After enabling the proxy service, the system periodically performs health checks on providers in the failover queue:
|
||||
|
||||
1. Sends a request using the configured test model
|
||||
2. Updates health status based on the response
|
||||
3. Unhealthy providers are temporarily skipped
|
||||
|
||||
### Circuit Breaker Recovery
|
||||
|
||||
When a provider recovers from a circuit-broken state:
|
||||
|
||||
1. Performs a model test to verify availability
|
||||
2. If the test passes, normal status is restored
|
||||
3. If the test fails, the circuit breaker remains active
|
||||
|
||||
## FAQ
|
||||
|
||||
### Test Fails But Actually Available
|
||||
|
||||
**Possible causes**:
|
||||
- The test model differs from the actually used model
|
||||
- The provider doesn't support the configured test model
|
||||
|
||||
**Solutions**:
|
||||
- Change the test model to one supported by the provider
|
||||
- Check the provider's model list
|
||||
|
||||
### High Latency
|
||||
|
||||
**Possible causes**:
|
||||
- Network latency
|
||||
- High server load on the provider
|
||||
- Slow model response
|
||||
|
||||
**Solutions**:
|
||||
- Use a faster test model
|
||||
- Adjust the degradation threshold
|
||||
- Consider using mirror endpoints
|
||||
|
||||
### Frequent Timeouts
|
||||
|
||||
**Possible causes**:
|
||||
- Timeout set too short
|
||||
- Unstable network
|
||||
- Unstable provider service
|
||||
|
||||
**Solutions**:
|
||||
- Increase the timeout
|
||||
- Increase retry count
|
||||
- Check network connection
|
||||
|
||||
## Notes
|
||||
|
||||
- Model testing consumes a small amount of API quota
|
||||
- Recommend using low-cost models for testing
|
||||
- Testing frequency should not be too high to avoid wasting quota
|
||||
- Different providers may support different models
|
||||
Reference in New Issue
Block a user