解决前端在生产环境构建失败的问题

frontend/src/assets/trafficapi_ai_call_documentation.md

+# TrafficAPI AI 模型调用文档
+
+## 概述
+
+TrafficAPI 是一个 AI API 网关平台，用于分发和管理 AI 产品订阅的 API 配额。它支持 Claude、OpenAI、Gemini 等多种 AI 模型，提供统一的 API 接口和智能调度功能。
+
+## 接入地址
+
+| 项目 | 值 |
+|------|----|
+| Base URL | `https://trafficapi.fcluadecodex.xyz` |
+| Claude 端点 | `https://trafficapi.fcluadecodex.xyz/v1/messages` |
+| OpenAI 端点 | `https://trafficapi.fcluadecodex.xyz/v1/chat/completions` |
+| Gemini 端点 | `https://trafficapi.fcluadecodex.xyz/v1beta/models/{model}%3AgenerateContent` |
+
+> **注意**：Gemini 端点路径中的 `%3A` 是冒号 `:` 的 URL 编码，curl 及各语言 HTTP 客户端需使用编码后的形式。
+
+## 环境变量约定
+
+文档中所有调用示例均通过以下环境变量引用凭据，请在运行前预先配置：
+
+```bash
+export TRAFFICAPI_BASE_URL="https://trafficapi.fcluadecodex.xyz"
+export CLAUDE_API_KEY="your-claude-api-key"
+export OPENAI_API_KEY="your-openai-api-key"
+export GEMINI_API_KEY="your-gemini-api-key"
+```
+
+## 目录
+
+1. [TrafficAPI 基本原理](#TrafficAPI-基本原理)
+2. [认证和 API Key 获取方式](#认证和-api-key-获取方式)
+3. [Claude 模型调用](#claude-模型调用)
+   - [HTTP API 调用](#http-api-调用)
+   - [SDK 调用](#sdk-调用)
+4. [OpenAI 模型调用](#openai-模型调用)
+   - [HTTP API 调用](#http-api-调用-1)
+   - [SDK 调用](#sdk-调用-1)
+5. [Gemini 模型调用](#gemini-模型调用)
+   - [HTTP API 调用](#http-api-调用-2)
+   - [SDK 调用](#sdk-调用-2)
+6. [流式响应处理](#流式响应处理)
+7. [错误处理和重试机制](#错误处理和重试机制)
+8. [性能优化建议](#性能优化建议)
+
+## TrafficAPI 基本原理
+
+### 架构设计
+
+TrafficAPI 作为 AI API 中转服务，其核心原理如下：
+
+1. **统一网关层**：提供标准化的 API 端点，兼容 Claude、OpenAI、Gemini 等不同厂商的 API 协议
+2. **智能调度**：根据账号状态、负载情况、成本等因素智能选择上游账号
+3. **粘性会话**：支持会话级别的账号绑定，确保同一会话的请求路由到同一上游账号
+4. **配额管理**：精确追踪 Token 使用量，实现按量计费
+5. **并发控制**：用户级和账号级的并发限制，防止资源滥用
+
+### 核心功能
+
+- **多账号管理**：支持多种上游账号类型（OAuth、API Key）
+- **API Key 分发**：为用户生成和管理 API Key
+- **精确计费**：Token 级别的用量追踪和成本计算
+- **智能调度**：智能账号选择，支持粘性会话
+- **并发控制**：用户级和账号级并发限制
+- **速率限制**：可配置的请求和 Token 速率限制
+
+## 认证和 API Key 获取方式
+
+### 1. 管理员获取 API Key
+
+1. 登录 TrafficAPI 管理后台
+2. 进入「API Keys」管理页面
+3. 点击「Create API Key」生成新的 API Key
+4. 复制生成的 API Key（格式：`sk-xxxxxxxxxxxxxxxx`）
+
+### 2. 用户获取 API Key
+
+1. 用户注册并登录 TrafficAPI 平台
+2. 在用户面板中查看或生成 API Key
+3. 管理员可以为用户分配 API Key
+
+### 3. API Key 使用方式
+
+在 HTTP 请求头中添加：
+```http
+Authorization: Bearer $YOUR_API_KEY
+```
+
+或者使用 `x-api-key` 头：
+```http
+x-api-key: $YOUR_API_KEY
+```
+
+
+## HTTP 请求参数详解
+
+### 请求头参数
+
+| 参数名 | 是否必填 | 说明 | 示例值 |
+|--------|----------|------|--------|
+| Authorization | 是 | Bearer Token 认证 | `Bearer sk-xxx` |
+| Content-Type | 是 | 请求体格式 | `application/json` |
+| Accept | 否 | 响应格式 | `application/json` 或 `text/event-stream` |
+| User-Agent | 否 | 客户端标识 | `MyApp/1.0` |
+| X-Request-ID | 否 | 请求唯一标识 | `req_123456` |
+
+### 请求体参数（通用）
+
+| 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
+|--------|------|----------|------|--------|
+| model | string | 是 | 模型名称 | `claude-3-sonnet-20241022` |
+| messages | array | 是 | 消息数组 | `[{"role": "user", "content": "Hello"}]` |
+| max_tokens | integer | 否 | 最大生成 token 数 | `1000` |
+| temperature | number | 否 | 温度参数（0.0-2.0） | `0.7` |
+| stream | boolean | 否 | 是否启用流式响应 | `true` |
+| top_p | number | 否 | 核采样参数（0.0-1.0） | `0.9` |
+| frequency_penalty | number | 否 | 频率惩罚（-2.0-2.0） | `0.0` |
+| presence_penalty | number | 否 | 存在惩罚（-2.0-2.0） | `0.0` |
+
+### Claude 特有参数
+
+| 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
+|--------|------|----------|------|--------|
+| system | string | 否 | 系统提示 | `"You are a helpful assistant."` |
+| max_tokens | integer | 否 | 最大生成 token 数 | `4096` |
+
+### OpenAI 特有参数
+
+| 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
+|--------|------|----------|------|--------|
+| n | integer | 否 | 生成多个选择 | `1` |
+| stop | string/array | 否 | 停止序列 | `["\n", "Human:"]` |
+| logprobs | integer | 否 | 返回 token 对数概率 | `null` |
+
+### Gemini 特有参数
+
+| 参数名 | 类型 | 是否必填 | 说明 | 示例值 |
+|--------|------|----------|------|--------|
+| safetySettings | array | 否 | 安全设置 | `[{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"}]` |
+| generationConfig | object | 否 | 生成配置 | `{"temperature": 0.7, "maxOutputTokens": 1000}` |
+
+## 响应参数详解
+
+### 成功响应
+
+```json
+{
+  "id": "chatcmpl-123",
+  "object": "chat.completion",
+  "created": 1677652288,
+  "model": "claude-3-sonnet-20241022",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "Hello! How can I help you today?"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 10,
+    "completion_tokens": 15,
+    "total_tokens": 25
+  }
+}
+```
+
+### 响应字段说明
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| id | string | 请求唯一标识 |
+| object | string | 对象类型 |
+| created | integer | 创建时间戳 |
+| model | string | 使用的模型 |
+| choices | array | 生成结果数组 |
+| usage | object | Token 使用统计 |
+| choices[].index | integer | 选择索引 |
+| choices[].message | object | 消息内容 |
+| choices[].finish_reason | string | 完成原因 |
+| usage.prompt_tokens | integer | 提示 token 数 |
+| usage.completion_tokens | integer | 生成 token 数 |
+| usage.total_tokens | integer | 总 token 数 |
+## Claude 模型调用
+
+### HTTP API 调用
+
+#### 基础信息
+- **端点**：`/v1/messages`
+- **协议**：兼容 Anthropic Claude API
+- **Content-Type**：`application/json`
+
+#### curl 示例
+
+```bash
+# 非流式调用
+curl -X POST "https://trafficapi.fcluadecodex.xyz/v1/messages" \
+  -H "Authorization: Bearer $CLAUDE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 1024,
+    "messages": [
+      {
+        "role": "user",
+        "content": "Hello, how are you?"
+      }
+    ]
+  }'
+
+# 流式调用
+curl -X POST "https://trafficapi.fcluadecodex.xyz/v1/messages" \
+  -H "Authorization: Bearer $CLAUDE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "anthropic-version: 2023-06-01" \
+  -d '{
+    "model": "claude-sonnet-4-6",
+    "max_tokens": 1024,
+    "messages": [
+      {
+        "role": "user",
+        "content": "Hello, how are you?"
+      }
+    ],
+    "stream": true
+  }'
+```
+
+#### Python 示例
+
+```python
+import requests
+import json
+
+class TrafficAPIClient:
+    def __init__(self, base_url, api_key):
+        self.base_url = base_url
+        self.api_key = api_key
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "anthropic-version": "2023-06-01"
+        }
+    
+    def create_message(self, model, messages, max_tokens=1024, stream=False):
+        url = f"{self.base_url}/v1/messages"
+        payload = {
+            "model": model,
+            "max_tokens": max_tokens,
+            "messages": messages,
+            "stream": stream
+        }
+        
+        response = requests.post(url, headers=self.headers, json=payload, stream=stream)
+        
+        if stream:
+            return self._handle_stream_response(response)
+        else:
+            return response.json()
+    
+    def _handle_stream_response(self, response):
+        for line in response.iter_lines():
+            if line:
+                line = line.decode('utf-8')
+                if line.startswith('data: '):
+                    data = line[6:]
+                    if data == '[DONE]':
+                        break
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+
+# 使用示例
+import os
+client = TrafficAPIClient(
+    base_url=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz"),
+    api_key=os.environ["CLAUDE_API_KEY"]
+)
+
+# 非流式调用
+response = client.create_message(
+    model="claude-sonnet-4-6",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ],
+    max_tokens=1024,
+    stream=False
+)
+print(response)
+
+# 流式调用
+for chunk in client.create_message(
+    model="claude-sonnet-4-6",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ],
+    max_tokens=1024,
+    stream=True
+):
+    print(chunk)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### Go 示例
+
+```go
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+)
+
+type Message struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}
+
+type ClaudeRequest struct {
+	Model      string    `json:"model"`
+	MaxTokens  int       `json:"max_tokens"`
+	Messages   []Message `json:"messages"`
+	Stream     bool      `json:"stream"`
+}
+
+type ClaudeResponse struct {
+	ID           string `json:"id"`
+	Type         string `json:"type"`
+	Role         string `json:"role"`
+	Content      []struct {
+		Type string `json:"type"`
+		Text string `json:"text"`
+	} `json:"content"`
+	Model        string `json:"model"`
+	StopReason   string `json:"stop_reason"`
+	StopSequence string `json:"stop_sequence"`
+	Usage        struct {
+		InputTokens  int `json:"input_tokens"`
+		OutputTokens int `json:"output_tokens"`
+	} `json:"usage"`
+}
+
+type TrafficAPIClient struct {
+	BaseURL string
+	APIKey  string
+}
+
+func NewTrafficAPIClient(baseURL, apiKey string) *TrafficAPIClient {
+	return &TrafficAPIClient{
+		BaseURL: baseURL,
+		APIKey:  apiKey,
+	}
+}
+
+func (c *TrafficAPIClient) CreateMessage(req ClaudeRequest) (*ClaudeResponse, error) {
+	url := c.BaseURL + "/v1/messages"
+	
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("anthropic-version", "2023-06-01")
+	
+	client := &http.Client{}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API error: %s, body: %s", resp.Status, string(body))
+	}
+	
+	var claudeResp ClaudeResponse
+	if err := json.NewDecoder(resp.Body).Decode(&claudeResp); err != nil {
+		return nil, err
+	}
+	
+	return &claudeResp, nil
+}
+
+func (c *TrafficAPIClient) CreateMessageStream(req ClaudeRequest) (<-chan string, error) {
+	req.Stream = true
+	url := c.BaseURL + "/v1/messages"
+	
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("anthropic-version", "2023-06-01")
+	
+	client := &http.Client{}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API error: %s, body: %s", resp.Status, string(body))
+	}
+	
+	ch := make(chan string)
+	go func() {
+		defer resp.Body.Close()
+		defer close(ch)
+		
+		reader := bufio.NewReader(resp.Body)
+		for {
+			line, err := reader.ReadString('\n')
+			if err != nil {
+				if err == io.EOF {
+					break
+				}
+				return
+			}
+			
+			line = strings.TrimSpace(line)
+			if strings.HasPrefix(line, "data: ") {
+				data := line[6:]
+				if data == "[DONE]" {
+					break
+				}
+				ch <- data
+			}
+		}
+	}()
+	
+	return ch, nil
+}
+
+// 使用示例
+func main() {
+	baseURL := os.Getenv("TRAFFICAPI_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://trafficapi.fcluadecodex.xyz"
+	}
+	client := NewTrafficAPIClient(baseURL, os.Getenv("CLAUDE_API_KEY"))
+	
+	// 非流式调用
+	req := ClaudeRequest{
+		Model:     "claude-sonnet-4-6",
+		MaxTokens: 1024,
+		Messages: []Message{
+			{Role: "user", Content: "Hello, how are you?"},
+		},
+		Stream: false,
+	}
+	
+	resp, err := client.CreateMessage(req)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+	
+	fmt.Printf("Response: %+v\n", resp)
+	
+	// 流式调用
+	req.Stream = true
+	ch, err := client.CreateMessageStream(req)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+	
+	for chunk := range ch {
+		fmt.Printf("Chunk: %s\n", chunk)
+	}
+}
+```
+
+**Go SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址
+- `http_client`: 可选，自定义 HTTP 客户端
+
+**聊天完成参数：**
+- `Model`: 必填，模型名称
+- `Messages`: 必填，消息数组
+- `MaxTokens`: 可选，最大生成 token 数
+- `Temperature`: 可选，温度参数
+- `Stream`: 可选，是否启用流式响应
+- `TopP`: 可选，核采样参数
+- `FrequencyPenalty`: 可选，频率惩罚
+- `PresencePenalty`: 可选，存在惩罚
+
+
+### SDK 调用
+
+#### 使用官方 Anthropic SDK
+
+```python
+import anthropic
+from anthropic import Anthropic
+
+# 配置 TrafficAPI 作为代理
+import os
+client = Anthropic(
+    api_key=os.environ["CLAUDE_API_KEY"],
+    base_url=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz")  # 无需 /v1 后缀，SDK 会自动添加
+)
+
+# 调用 Claude
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ]
+)
+
+print(response.content[0].text)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### 使用 LangChain
+
+```python
+from langchain.chat_models import ChatAnthropic
+from langchain.schema import HumanMessage
+
+# 配置 LangChain
+import os
+chat = ChatAnthropic(
+    anthropic_api_key=os.environ["CLAUDE_API_KEY"],
+    anthropic_api_url=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz"),
+    model="claude-sonnet-4-6"
+)
+
+# 调用
+messages = [HumanMessage(content="Hello, how are you?")]
+response = chat(messages)
+print(response.content)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+## OpenAI 模型调用
+
+### HTTP API 调用
+
+#### 基础信息
+- **端点**：`/v1/chat/completions`
+- **协议**：兼容 OpenAI Chat Completions API
+- **Content-Type**：`application/json`
+
+#### curl 示例
+
+```bash
+# 非流式调用
+curl -X POST "https://trafficapi.fcluadecodex.xyz/v1/chat/completions" \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-5.2",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Hello, how are you?"
+      }
+    ],
+    "max_tokens": 1024
+  }'
+
+# 流式调用
+curl -X POST "https://trafficapi.fcluadecodex.xyz/v1/chat/completions" \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "gpt-5.2",
+    "messages": [
+      {
+        "role": "user",
+        "content": "Hello, how are you?"
+      }
+    ],
+    "max_tokens": 1024,
+    "stream": true
+  }'
+```
+
+#### Python 示例
+
+```python
+import requests
+import json
+
+class TrafficAPIOpenAIClient:
+    def __init__(self, base_url, api_key):
+        self.base_url = base_url
+        self.api_key = api_key
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json"
+        }
+    
+    def create_chat_completion(self, model, messages, max_tokens=1024, stream=False):
+        url = f"{self.base_url}/v1/chat/completions"
+        payload = {
+            "model": model,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "stream": stream
+        }
+        
+        response = requests.post(url, headers=self.headers, json=payload, stream=stream)
+        
+        if stream:
+            return self._handle_stream_response(response)
+        else:
+            return response.json()
+    
+    def _handle_stream_response(self, response):
+        for line in response.iter_lines():
+            if line:
+                line = line.decode('utf-8')
+                if line.startswith('data: '):
+                    data = line[6:]
+                    if data == '[DONE]':
+                        break
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+
+# 使用示例
+import os
+client = TrafficAPIOpenAIClient(
+    base_url=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz"),
+    api_key=os.environ["OPENAI_API_KEY"]
+)
+
+# 非流式调用
+response = client.create_chat_completion(
+    model="gpt-5.2",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ],
+    max_tokens=1024,
+    stream=False
+)
+print(response["choices"][0]["message"]["content"])
+
+# 流式调用
+for chunk in client.create_chat_completion(
+    model="gpt-5.2",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ],
+    max_tokens=1024,
+    stream=True
+):
+    if "choices" in chunk and chunk["choices"]:
+        delta = chunk["choices"][0].get("delta", {})
+        if "content" in delta:
+            print(delta["content"], end="", flush=True)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### Go 示例
+
+```go
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+)
+
+type OpenAIMessage struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}
+
+type OpenAIRequest struct {
+	Model    string          `json:"model"`
+	Messages []OpenAIMessage `json:"messages"`
+	MaxTokens int           `json:"max_tokens"`
+	Stream   bool           `json:"stream"`
+}
+
+type OpenAIResponse struct {
+	ID      string `json:"id"`
+	Object  string `json:"object"`
+	Created int64  `json:"created"`
+	Model   string `json:"model"`
+	Choices []struct {
+		Index        int `json:"index"`
+		Message      struct {
+			Role    string `json:"role"`
+			Content string `json:"content"`
+		} `json:"message"`
+		FinishReason string `json:"finish_reason"`
+	} `json:"choices"`
+	Usage struct {
+		PromptTokens     int `json:"prompt_tokens"`
+		CompletionTokens int `json:"completion_tokens"`
+		TotalTokens      int `json:"total_tokens"`
+	} `json:"usage"`
+}
+
+type TrafficAPIOpenAIClient struct {
+	BaseURL string
+	APIKey  string
+}
+
+func NewTrafficAPIOpenAIClient(baseURL, apiKey string) *TrafficAPIOpenAIClient {
+	return &TrafficAPIOpenAIClient{
+		BaseURL: baseURL,
+		APIKey:  apiKey,
+	}
+}
+
+func (c *TrafficAPIOpenAIClient) CreateChatCompletion(req OpenAIRequest) (*OpenAIResponse, error) {
+	url := c.BaseURL + "/v1/chat/completions"
+	
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)
+	httpReq.Header.Set("Content-Type", "application/json")
+	
+	client := &http.Client{}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API error: %s, body: %s", resp.Status, string(body))
+	}
+	
+	var openaiResp OpenAIResponse
+	if err := json.NewDecoder(resp.Body).Decode(&openaiResp); err != nil {
+		return nil, err
+	}
+	
+	return &openaiResp, nil
+}
+
+func (c *TrafficAPIOpenAIClient) CreateChatCompletionStream(req OpenAIRequest) (<-chan string, error) {
+	req.Stream = true
+	url := c.BaseURL + "/v1/chat/completions"
+	
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)
+	httpReq.Header.Set("Content-Type", "application/json")
+	
+	client := &http.Client{}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API error: %s, body: %s", resp.Status, string(body))
+	}
+	
+	ch := make(chan string)
+	go func() {
+		defer resp.Body.Close()
+		defer close(ch)
+		
+		reader := bufio.NewReader(resp.Body)
+		for {
+			line, err := reader.ReadString('\n')
+			if err != nil {
+				if err == io.EOF {
+					break
+				}
+				return
+			}
+			
+			line = strings.TrimSpace(line)
+			if strings.HasPrefix(line, "data: ") {
+				data := line[6:]
+				if data == "[DONE]" {
+					break
+				}
+				ch <- data
+			}
+		}
+	}()
+	
+	return ch, nil
+}
+
+// 使用示例
+func main() {
+	baseURL := os.Getenv("TRAFFICAPI_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://trafficapi.fcluadecodex.xyz"
+	}
+	client := NewTrafficAPIOpenAIClient(baseURL, os.Getenv("OPENAI_API_KEY"))
+	
+	// 非流式调用
+	req := OpenAIRequest{
+		Model: "gpt-5.2",
+		Messages: []OpenAIMessage{
+			{Role: "user", Content: "Hello, how are you?"},
+		},
+		MaxTokens: 1024,
+		Stream:   false,
+	}
+	
+	resp, err := client.CreateChatCompletion(req)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+	
+	fmt.Printf("Response: %+v\n", resp)
+	
+	// 流式调用
+	req.Stream = true
+	ch, err := client.CreateChatCompletionStream(req)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+	
+	for chunk := range ch {
+		fmt.Printf("Chunk: %s\n", chunk)
+	}
+}
+```
+
+**Go SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址
+- `http_client`: 可选，自定义 HTTP 客户端
+
+**聊天完成参数：**
+- `Model`: 必填，模型名称
+- `Messages`: 必填，消息数组
+- `MaxTokens`: 可选，最大生成 token 数
+- `Temperature`: 可选，温度参数
+- `Stream`: 可选，是否启用流式响应
+- `TopP`: 可选，核采样参数
+- `FrequencyPenalty`: 可选，频率惩罚
+- `PresencePenalty`: 可选，存在惩罚
+
+
+### SDK 调用
+
+#### 使用官方 OpenAI SDK
+
+```python
+import openai
+
+# 配置 TrafficAPI 作为代理
+import os
+client = openai.OpenAI(
+    api_key=os.environ["OPENAI_API_KEY"],
+    base_url=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz") + "/v1"
+)
+
+# 调用 GPT
+response = client.chat.completions.create(
+    model="gpt-5.2",
+    messages=[
+        {"role": "user", "content": "Hello, how are you?"}
+    ],
+    max_tokens=1024
+)
+
+print(response.choices[0].message.content)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### 使用 LangChain
+
+```python
+from langchain.chat_models import ChatOpenAI
+from langchain.schema import HumanMessage
+
+# 配置 LangChain
+import os
+chat = ChatOpenAI(
+    openai_api_key=os.environ["OPENAI_API_KEY"],
+    openai_api_base=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz") + "/v1",
+    model_name="gpt-5.2"
+)
+
+# 调用
+messages = [HumanMessage(content="Hello, how are you?")]
+response = chat(messages)
+print(response.content)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+## Gemini 模型调用
+
+### HTTP API 调用
+
+#### 基础信息
+- **端点**：`/v1beta/models/{model}:generateContent`
+- **协议**：兼容 Google Gemini API
+- **Content-Type**：`application/json`
+
+#### curl 示例
+
+```bash
+# 非流式调用
+curl -X POST "https://trafficapi.fcluadecodex.xyz/v1beta/models/gemini-3.1-flash-lite-preview%3AgenerateContent" \
+  -H "Authorization: Bearer $GEMINI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "contents": [
+      {
+        "parts": [
+          {
+            "text": "Hello, how are you?"
+          }
+        ]
+      }
+    ]
+  }'
+
+# 流式调用（使用 streamGenerateContent 端点，注意 %3A 是 : 的 URL 编码）
+curl -X POST "https://trafficapi.fcluadecodex.xyz/v1beta/models/gemini-3.1-flash-lite-preview%3AstreamGenerateContent" \
+  -H "Authorization: Bearer $GEMINI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "contents": [
+      {
+        "parts": [
+          {
+            "text": "Hello, how are you?"
+          }
+        ]
+      }
+    ]
+  }'
+```
+
+#### Python 示例
+
+```python
+import requests
+import json
+
+class TrafficAPIGeminiClient:
+    def __init__(self, base_url, api_key):
+        self.base_url = base_url
+        self.api_key = api_key
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json"
+        }
+    
+    def generate_content(self, model, contents):
+        # 注意：路径中的 : 需要 URL 编码为 %3A
+        url = f"{self.base_url}/v1beta/models/{model}%3AgenerateContent"
+        payload = {"contents": contents}
+        response = requests.post(url, headers=self.headers, json=payload)
+        return response.json()
+    
+    def generate_content_stream(self, model, contents):
+        # 注意：路径中的 : 需要 URL 编码为 %3A
+        url = f"{self.base_url}/v1beta/models/{model}%3AstreamGenerateContent"
+        payload = {"contents": contents}
+        response = requests.post(url, headers=self.headers, json=payload, stream=True)
+        return self._handle_stream_response(response)
+    
+    def _handle_stream_response(self, response):
+        # streamGenerateContent 返回 SSE 格式，每行以 "data: " 开头
+        for line in response.iter_lines():
+            if line:
+                line = line.decode('utf-8')
+                if line.startswith('data: '):
+                    data = line[6:]
+                    if data == '[DONE]':
+                        break
+                    try:
+                        yield json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+
+# 使用示例
+import os
+client = TrafficAPIGeminiClient(
+    base_url=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz"),
+    api_key=os.environ["GEMINI_API_KEY"]
+)
+
+# 非流式调用
+response = client.generate_content(
+    model="gemini-3.1-flash-lite-preview",
+    contents=[
+        {
+            "parts": [
+                {"text": "Hello, how are you?"}
+            ]
+        }
+    ],
+    stream=False
+)
+print(response["candidates"][0]["content"]["parts"][0]["text"])
+
+# 流式调用（使用 streamGenerateContent 端点）
+for chunk in client.generate_content_stream(
+    model="gemini-3.1-flash-lite-preview",
+    contents=[
+        {
+            "parts": [
+                {"text": "Hello, how are you?"}
+            ]
+        }
+    ]
+):
+    if "candidates" in chunk and chunk["candidates"]:
+        for candidate in chunk["candidates"]:
+            if "content" in candidate and "parts" in candidate["content"]:
+                for part in candidate["content"]["parts"]:
+                    if "text" in part:
+                        print(part["text"], end="", flush=True)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### Go 示例
+
+```go
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+)
+
+type GeminiPart struct {
+	Text string `json:"text"`
+}
+
+type GeminiContent struct {
+	Parts []GeminiPart `json:"parts"`
+}
+
+type GeminiRequest struct {
+	Contents []GeminiContent `json:"contents"`
+	GenerationConfig *struct {
+		CandidateCount int `json:"candidateCount"`
+	} `json:"generationConfig,omitempty"`
+}
+
+type GeminiResponse struct {
+	Candidates []struct {
+		Content struct {
+			Parts []GeminiPart `json:"parts"`
+		} `json:"content"`
+		FinishReason string `json:"finishReason"`
+	} `json:"candidates"`
+	UsageMetadata *struct {
+		PromptTokenCount     int `json:"promptTokenCount"`
+		CandidatesTokenCount int `json:"candidatesTokenCount"`
+		TotalTokenCount      int `json:"totalTokenCount"`
+	} `json:"usageMetadata"`
+}
+
+type TrafficAPIGeminiClient struct {
+	BaseURL string
+	APIKey  string
+}
+
+func NewTrafficAPIGeminiClient(baseURL, apiKey string) *TrafficAPIGeminiClient {
+	return &TrafficAPIGeminiClient{
+		BaseURL: baseURL,
+		APIKey:  apiKey,
+	}
+}
+
+func (c *TrafficAPIGeminiClient) GenerateContent(model string, req GeminiRequest) (*GeminiResponse, error) {
+	// 注意：路径中的 : 需要 URL 编码为 %3A（%%3A 在 Sprintf 中输出字面量 %3A）
+	url := fmt.Sprintf("%s/v1beta/models/%s%%3AgenerateContent", c.BaseURL, model)
+	
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)
+	httpReq.Header.Set("Content-Type", "application/json")
+	
+	client := &http.Client{}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API error: %s, body: %s", resp.Status, string(body))
+	}
+	
+	var geminiResp GeminiResponse
+	if err := json.NewDecoder(resp.Body).Decode(&geminiResp); err != nil {
+		return nil, err
+	}
+	
+	return &geminiResp, nil
+}
+
+func (c *TrafficAPIGeminiClient) GenerateContentStream(model string, req GeminiRequest) (<-chan string, error) {
+	url := fmt.Sprintf("%s/v1beta/models/%s%%3AstreamGenerateContent", c.BaseURL, model)
+	
+	reqBody, err := json.Marshal(req)
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(reqBody))
+	if err != nil {
+		return nil, err
+	}
+	
+	httpReq.Header.Set("Authorization", "Bearer "+c.APIKey)
+	httpReq.Header.Set("Content-Type", "application/json")
+	
+	client := &http.Client{}
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return nil, err
+	}
+	
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("API error: %s, body: %s", resp.Status, string(body))
+	}
+	
+	ch := make(chan string)
+	go func() {
+		defer resp.Body.Close()
+		defer close(ch)
+		
+		// streamGenerateContent 返回 SSE 格式，每行以 "data: " 开头
+		scanner := bufio.NewScanner(resp.Body)
+		for scanner.Scan() {
+			line := scanner.Text()
+			if strings.HasPrefix(line, "data: ") {
+				data := line[6:]
+				if data == "[DONE]" {
+					break
+				}
+				if data != "" {
+					ch <- data
+				}
+			}
+		}
+	}()
+	
+	return ch, nil
+}
+
+// 使用示例
+func main() {
+	baseURL := os.Getenv("TRAFFICAPI_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://trafficapi.fcluadecodex.xyz"
+	}
+	client := NewTrafficAPIGeminiClient(baseURL, os.Getenv("GEMINI_API_KEY"))
+	
+	// 非流式调用
+	req := GeminiRequest{
+		Contents: []GeminiContent{
+			{
+				Parts: []GeminiPart{
+					{Text: "Hello, how are you?"},
+				},
+			},
+		},
+	}
+	
+	resp, err := client.GenerateContent("gemini-3.1-flash-lite-preview", req)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+	
+	fmt.Printf("Response: %+v\n", resp)
+	
+	// 流式调用
+	ch, err := client.GenerateContentStream("gemini-3.1-flash-lite-preview", req)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		return
+	}
+	
+	for chunk := range ch {
+		fmt.Printf("Chunk: %s\n", chunk)
+	}
+}
+```
+
+**Go SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址
+- `http_client`: 可选，自定义 HTTP 客户端
+
+**聊天完成参数：**
+- `Model`: 必填，模型名称
+- `Messages`: 必填，消息数组
+- `MaxTokens`: 可选，最大生成 token 数
+- `Temperature`: 可选，温度参数
+- `Stream`: 可选，是否启用流式响应
+- `TopP`: 可选，核采样参数
+- `FrequencyPenalty`: 可选，频率惩罚
+- `PresencePenalty`: 可选，存在惩罚
+
+
+### SDK 调用
+
+#### 使用官方 Google Generative AI SDK
+
+```python
+import google.generativeai as genai
+
+# 配置 TrafficAPI 作为代理
+import os
+_base = os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz")
+genai.configure(
+    api_key=os.environ["GEMINI_API_KEY"],
+    transport="rest",
+    client_options={
+        "api_endpoint": f"{_base}/v1beta"
+    }
+)
+
+# 创建模型
+model = genai.GenerativeModel("gemini-3.1-flash-lite-preview")
+
+# 调用
+response = model.generate_content("Hello, how are you?")
+print(response.text)
+
+# 流式调用
+response = model.generate_content("Hello, how are you?", stream=True)
+for chunk in response:
+    print(chunk.text, end="", flush=True)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### 使用 LangChain
+
+```python
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain.schema import HumanMessage
+
+# 配置 LangChain
+import os
+chat = ChatGoogleGenerativeAI(
+    google_api_key=os.environ["GEMINI_API_KEY"],
+    google_api_base=os.environ.get("TRAFFICAPI_BASE_URL", "https://trafficapi.fcluadecodex.xyz") + "/v1beta",
+    model="gemini-3.1-flash-lite-preview"
+)
+
+# 调用
+messages = [HumanMessage(content="Hello, how are you?")]
+response = chat(messages)
+print(response.content)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+## 流式响应处理
+
+### 通用流式响应处理模式
+
+TrafficAPI 支持所有模型的流式响应，处理模式类似但略有不同：
+
+#### Claude 流式响应格式
+```
+event: message_start
+data: {"type":"message_start","message":{"model":"claude-sonnet-4-6","id":"msg_xxx","type":"message","role":"assistant","content":[],...}}
+
+event: content_block_start
+data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
+
+event: content_block_delta
+data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" there"}}
+
+event: message_stop
+data: {"type":"message_stop"}
+```
+
+#### OpenAI 流式响应格式
+```
+data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1677652288, "model": "gpt-5.2", "choices": [{"index": 0, "delta": {"content": "Hello"}, "finish_reason": null}]}
+data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1677652288, "model": "gpt-5.2", "choices": [{"index": 0, "delta": {"content": " there"}, "finish_reason": null}]}
+data: [DONE]
+```
+
+#### Gemini 流式响应格式（streamGenerateContent 端点，SSE 格式）
+```
+data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Hello"}]},"finishReason":"","index":0}],"usageMetadata":{...},"modelVersion":"gemini-3.1-flash-lite-preview"}
+
+data: {"candidates":[{"content":{"role":"model","parts":[{"text":" there"}]},"finishReason":"STOP","index":0}],"usageMetadata":{...}}
+```
+
+### 流式处理最佳实践
+
+1. **缓冲区管理**：适当缓冲流式数据，避免频繁的 UI 更新
+2. **错误处理**：流式响应中可能包含错误信息，需要实时检测
+3. **连接保持**：确保网络连接稳定，必要时实现重连机制
+4. **资源清理**：及时关闭流式连接，释放资源
+
+### Python 通用流式处理函数
+
+```python
+def handle_stream_response(response, callback):
+    """
+    通用流式响应处理函数
+    
+    Args:
+        response: requests.Response 对象
+        callback: 处理每个数据块的函数，接收解析后的 JSON 数据
+    """
+    buffer = ""
+    for line in response.iter_lines():
+        if line:
+            line = line.decode('utf-8')
+            
+            # 处理 SSE 格式（Claude/OpenAI）
+            if line.startswith('data: '):
+                data = line[6:]
+                if data == '[DONE]':
+                    break
+                
+                try:
+                    json_data = json.loads(data)
+                    callback(json_data)
+                except json.JSONDecodeError:
+                    # 可能是 Gemini 的纯 JSON 流
+                    buffer += data
+                    try:
+                        json_data = json.loads(buffer)
+                        callback(json_data)
+                        buffer = ""
+                    except json.JSONDecodeError:
+                        continue
+            else:
+                # 处理 Gemini 的纯 JSON 流
+                buffer += line
+                try:
+                    json_data = json.loads(buffer)
+                    callback(json_data)
+                    buffer = ""
+                except json.JSONDecodeError:
+                    continue
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+## 错误处理和重试机制
+
+### 常见错误码
+
+| 状态码 | 错误类型 | 描述 | 处理建议 |
+|--------|----------|------|----------|
+| 400 | Bad Request | 请求参数错误 | 检查请求格式和参数 |
+| 401 | Unauthorized | API Key 无效或过期 | 检查 API Key 有效性 |
+| 403 | Forbidden | 权限不足 | 检查用户权限和配额 |
+| 429 | Too Many Requests | 请求频率超限 | 降低请求频率，实现退避重试 |
+| 500 | Internal Server Error | 服务器内部错误 | 等待后重试，联系管理员 |
+| 502 | Bad Gateway | 上游服务不可用 | 等待后重试 |
+| 503 | Service Unavailable | 服务暂时不可用 | 等待后重试 |
+
+### 重试策略实现
+
+#### Python 重试装饰器
+
+```python
+import time
+import random
+from functools import wraps
+
+def retry_with_exponential_backoff(
+    max_retries=5,
+    initial_delay=1,
+    exponential_base=2,
+    jitter=True,
+    retry_status_codes=[429, 500, 502, 503, 504]
+):
+    """指数退避重试装饰器"""
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            delay = initial_delay
+            for attempt in range(max_retries):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    # 检查是否需要重试
+                    should_retry = False
+                    if hasattr(e, 'status_code'):
+                        should_retry = e.status_code in retry_status_codes
+                    elif hasattr(e, 'response') and hasattr(e.response, 'status_code'):
+                        should_retry = e.response.status_code in retry_status_codes
+                    
+                    if not should_retry or attempt == max_retries - 1:
+                        raise
+                    
+                    # 计算延迟时间
+                    delay *= exponential_base ** attempt
+                    if jitter:
+                        delay = random.uniform(0, delay)
+                    
+                    print(f"Attempt {attempt + 1} failed, retrying in {delay:.2f} seconds...")
+                    time.sleep(delay)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+# 使用示例
+@retry_with_exponential_backoff(max_retries=3)
+def call_api_with_retry():
+    response = requests.post(...)
+    response.raise_for_status()
+    return response.json()
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### Go 重试实现
+
+```go
+package main
+
+import (
+	"fmt"
+	"math/rand"
+	"time"
+)
+
+type RetryConfig struct {
+	MaxRetries      int
+	InitialDelay    time.Duration
+	ExponentialBase float64
+	Jitter          bool
+	RetryStatusCodes []int
+}
+
+func NewDefaultRetryConfig() *RetryConfig {
+	return &RetryConfig{
+		MaxRetries:      5,
+		InitialDelay:    time.Second,
+		ExponentialBase: 2.0,
+		Jitter:          true,
+		RetryStatusCodes: []int{429, 500, 502, 503, 504},
+	}
+}
+
+func RetryWithExponentialBackoff(config *RetryConfig, fn func() error) error {
+	var lastErr error
+	delay := config.InitialDelay
+	
+	for attempt := 0; attempt < config.MaxRetries; attempt++ {
+		err := fn()
+		if err == nil {
+			return nil
+		}
+		
+		lastErr = err
+		
+		// 检查是否需要重试
+		shouldRetry := false
+		if apiErr, ok := err.(*APIError); ok {
+			for _, code := range config.RetryStatusCodes {
+				if apiErr.StatusCode == code {
+					shouldRetry = true
+					break
+				}
+			}
+		}
+		
+		if !shouldRetry || attempt == config.MaxRetries-1 {
+			break
+		}
+		
+		// 计算延迟时间
+		delay = time.Duration(float64(delay) * config.ExponentialBase)
+		if config.Jitter {
+			delay = time.Duration(float64(delay) * (0.5 + rand.Float64()))
+		}
+		
+		fmt.Printf("Attempt %d failed, retrying in %v...\n", attempt+1, delay)
+		time.Sleep(delay)
+	}
+	
+	return lastErr
+}
+
+// 使用示例
+func callAPIWithRetry() error {
+	config := NewDefaultRetryConfig()
+	return RetryWithExponentialBackoff(config, func() error {
+		resp, err := http.Post(...)
+		if err != nil {
+			return err
+		}
+		defer resp.Body.Close()
+		
+		if resp.StatusCode != http.StatusOK {
+			return &APIError{
+				StatusCode: resp.StatusCode,
+				Message:    "API request failed",
+			}
+		}
+		return nil
+	})
+}
+```
+
+**Go SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址
+- `http_client`: 可选，自定义 HTTP 客户端
+
+**聊天完成参数：**
+- `Model`: 必填，模型名称
+- `Messages`: 必填，消息数组
+- `MaxTokens`: 可选，最大生成 token 数
+- `Temperature`: 可选，温度参数
+- `Stream`: 可选，是否启用流式响应
+- `TopP`: 可选，核采样参数
+- `FrequencyPenalty`: 可选，频率惩罚
+- `PresencePenalty`: 可选，存在惩罚
+
+
+### 错误监控和告警
+
+1. **错误率监控**：监控 API 调用错误率，设置阈值告警
+2. **延迟监控**：监控 API 响应时间，识别性能问题
+3. **配额监控**：监控用户配额使用情况，提前预警
+4. **健康检查**：定期进行健康检查，确保服务可用性
+
+## 性能优化建议
+
+### 1. 连接池管理
+
+#### Python 连接池配置
+
+```python
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+# 创建会话并配置连接池
+session = requests.Session()
+
+# 配置重试策略
+retry_strategy = Retry(
+    total=3,
+    backoff_factor=1,
+    status_forcelist=[429, 500, 502, 503, 504],
+    allowed_methods=["POST", "GET"]
+)
+
+# 配置适配器
+adapter = HTTPAdapter(
+    max_retries=retry_strategy,
+    pool_connections=10,      # 连接池大小
+    pool_maxsize=10,         # 最大连接数
+    pool_block=False         # 是否阻塞等待连接
+)
+
+session.mount("http://", adapter)
+session.mount("https://", adapter)
+
+# 使用会话调用 API
+response = session.post(
+    "https://trafficapi.fcluadecodex.xyz/v1/chat/completions",
+    headers=headers,
+    json=payload,
+    timeout=30
+)
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+#### Go 连接池配置
+
+```go
+package main
+
+import (
+	"net/http"
+	"time"
+)
+
+func createHTTPClient() *http.Client {
+	transport := &http.Transport{
+		MaxIdleConns:        100,              // 最大空闲连接数
+		MaxIdleConnsPerHost: 10,               // 每个主机的最大空闲连接数
+		MaxConnsPerHost:     10,               // 每个主机的最大连接数
+		IdleConnTimeout:     90 * time.Second, // 空闲连接超时时间
+		TLSHandshakeTimeout: 10 * time.Second, // TLS 握手超时时间
+	}
+	
+	return &http.Client{
+		Transport: transport,
+		Timeout:   30 * time.Second, // 请求超时时间
+	}
+}
+
+// 使用共享的 HTTP 客户端
+var httpClient = createHTTPClient()
+
+func callAPI() (*http.Response, error) {
+	req, err := http.NewRequest("POST", "https://trafficapi.fcluadecodex.xyz/v1/chat/completions", nil)
+	if err != nil {
+		return nil, err
+	}
+	
+	return httpClient.Do(req)
+}
+```
+
+**Go SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址
+- `http_client`: 可选，自定义 HTTP 客户端
+
+**聊天完成参数：**
+- `Model`: 必填，模型名称
+- `Messages`: 必填，消息数组
+- `MaxTokens`: 可选，最大生成 token 数
+- `Temperature`: 可选，温度参数
+- `Stream`: 可选，是否启用流式响应
+- `TopP`: 可选，核采样参数
+- `FrequencyPenalty`: 可选，频率惩罚
+- `PresencePenalty`: 可选，存在惩罚
+
+
+### 2. 请求批量化
+
+对于多个独立的请求，可以考虑批量处理：
+
+```python
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+def batch_process_requests(requests_data, max_workers=5):
+    """批量处理请求"""
+    results = []
+    
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        # 提交所有任务
+        future_to_request = {
+            executor.submit(process_single_request, data): data 
+            for data in requests_data
+        }
+        
+        # 收集结果
+        for future in as_completed(future_to_request):
+            try:
+                result = future.result()
+                results.append(result)
+            except Exception as e:
+                print(f"Request failed: {e}")
+                results.append(None)
+    
+    return results
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+
+### 3. 缓存策略
+
+对于重复的查询，实现缓存机制：
+
+```python
+import hashlib
+import pickle
+from datetime import datetime, timedelta
+
+class APICache:
+    def __init__(self, ttl_seconds=300):
+        self.cache = {}
+        self.ttl = ttl_seconds
+    
+    def get_cache_key(self, endpoint, params):
+        """生成缓存键"""
+        key_data = f"{endpoint}:{json.dumps(params, sort_keys=True)}"
+        return hashlib.md5(key_data.encode()).hexdigest()
+    
+    def get(self, endpoint, params):
+        """获取缓存"""
+        key = self.get_cache_key(endpoint, params)
+        if key in self.cache:
+            cached_data, timestamp = self.cache[key]
+            if datetime.now() - timestamp < timedelta(seconds=self.ttl):
+                return cached_data
+        return None
+    
+    def set(self, endpoint, params, data):
+        """设置缓存"""
+        key = self.get_cache_key(endpoint, params)
+        self.cache[key] = (data, datetime.now())
+    
+    def clear(self):
+        """清空缓存"""
+        self.cache.clear()
+
+# 使用缓存
+cache = APICache(ttl_seconds=600)
+
+def cached_api_call(endpoint, params):
+    # 检查缓存
+    cached_result = cache.get(endpoint, params)
+    if cached_result:
+        return cached_result
+    
+    # 调用 API
+    result = call_api(endpoint, params)
+    
+    # 缓存结果
+    cache.set(endpoint, params, result)
+    
+    return result
+```
+
+**Python SDK 参数说明：**
+**初始化参数：**
+- `api_key`: 必填，TrafficAPI 的 API Key
+- `base_url`: 可选，TrafficAPI 服务地址，默认为官方地址
+- `timeout`: 可选，请求超时时间（秒）
+- `max_retries`: 可选，最大重试次数
+
+**聊天完成参数：**
+- `model`: 必填，模型名称
+- `messages`: 必填，消息列表，格式为 `[{"role": "user", "content": "..."}]`
+- `max_tokens`: 可选，最大生成 token 数
+- `temperature`: 可选，温度参数（0.0-2.0）
+- `stream`: 可选，是否启用流式响应
+- `top_p`: 可选，核采样参数
+- `frequency_penalty`: 可选，频率惩罚
+- `presence_penalty`: 可选，存在惩罚
+
+### 4. 安全最佳实践
+
+1. **API Key 管理**：
+   - 定期轮换 API Key
+   - 使用环境变量存储敏感信息
+   - 实现 Key 的访问控制
+
+2. **请求验证**：
+   - 验证输入参数
+   - 限制请求大小
+   - 实现速率限制
+
+3. **日志和审计**：
+   - 记录所有 API 调用
+   - 实现操作审计
+   - 监控异常行为
+
+
+
+## 注意事项
+
+### 1. 服务条款合规性
+
+使用 TrafficAPI 调用 AI 模型服务时，请注意：
+- 遵守上游服务提供商（Anthropic、OpenAI、Google）的服务条款
+- 了解并遵守相关法律法规
+- 合理使用 API 资源，避免滥用
+
+### 2. 安全性考虑
+
+1. **API Key 保护**：
+   - 不要在客户端代码中硬编码 API Key
+   - 使用环境变量或密钥管理服务
+   - 定期轮换 API Key
+
+2. **请求安全**：
+   - 验证用户输入，防止注入攻击
+   - 实现请求速率限制
+   - 监控异常请求模式
+
+3. **数据隐私**：
+   - 避免传输敏感个人信息
+   - 了解数据在传输和存储中的加密情况
+   - 遵守数据保护法规（如 GDPR、CCPA）
+
+### 3. 成本控制
+
+1. **用量监控**：
+   - 实时监控 Token 使用量
+   - 设置用量告警阈值
+   - 定期分析成本趋势
+
+2. **优化策略**：
+   - 使用缓存减少重复请求
+   - 优化提示词减少 Token 消耗
+   - 考虑使用成本更低的模型
+
+3. **预算管理**：
+   - 设置月度预算限制
+   - 实现自动化的成本控制
+   - 定期审查成本效益
+

frontend/src/views/user/DocsView.vue

@@ -38,7 +38,7 @@ import { onMounted, onUnmounted, ref, nextTick } from 'vue'
 import { Marked, Renderer } from 'marked'
 import DOMPurify from 'dompurify'
 import AppLayout from '@/components/layout/AppLayout.vue'
-import docRaw from '../../../../trafficapi_ai_call_documentation.md?raw'
+import docRaw from '@/assets/trafficapi_ai_call_documentation.md?raw'
 
 // ─── Slug ─────────────────────────────────────────────────────────────────────
 function slugify(text: string): string {