> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用者追蹤

> 透過 API 請求中的 user 欄位按使用者追蹤使用情況。適用於按使用者分析、成本分攤和濫用檢測。

ARouter 支援透過在 API 請求中傳遞 `user` 欄位來追蹤每個使用者的使用情況。這讓您可以將 API 成本歸因於應用程式中的特定使用者，並在使用者層級監控使用模式。

## 傳遞使用者 ID

在任何聊天補全請求中包含 `user` 欄位：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{"role": "user", "content": "Hello!"}],
  "user": "user_12345"
}
```

`user` 值可以是系統中識別終端使用者的任意字串——資料庫 ID、雜湊電子郵件或工作階段 ID 均可。ARouter 不驗證或解析此值。

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://api.arouter.ai/v1",
      apiKey: "lr_live_xxxx",
    });

    async function chatWithUser(userId: string, message: string) {
      const response = await client.chat.completions.create({
        model: "openai/gpt-5.4",
        messages: [{ role: "user", content: message }],
        user: userId,
      });
      return response.choices[0].message.content;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.arouter.ai/v1",
        api_key="lr_live_xxxx",
    )

    def chat_with_user(user_id: str, message: str) -> str:
        response = client.chat.completions.create(
            model="openai/gpt-5.4",
            messages=[{"role": "user", "content": message}],
            user=user_id,
        )
        return response.choices[0].message.content
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.arouter.ai/v1/chat/completions \
      -H "Authorization: Bearer lr_live_xxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "openai/gpt-5.4",
        "messages": [{"role": "user", "content": "Hello!"}],
        "user": "user_12345"
      }'
    ```
  </Tab>
</Tabs>

***

## 隱私注意事項

<Warning>
  請勿將個人識別資訊（PII）作為 `user` 值傳遞。請使用不透明識別碼，例如雜湊 ID 或資料庫主鍵。
</Warning>

建議做法：

```python theme={null}
import hashlib

# 在傳遞之前對使用者電子郵件進行雜湊處理
user_id = hashlib.sha256(user_email.encode()).hexdigest()[:16]

# 或使用不透明的資料庫 ID
user_id = str(user.id)  # 例如 "usr_abc123"
```

***

## 按使用者查看使用情況

使用者層級的使用資料可在[活動匯出](/zh-Hant/guides/administration/activity-export)中取得。每筆記錄都包含您傳遞的 `user` 欄位，讓您能夠：

* 計算每位使用者的 Token 消耗和成本
* 識別高使用量使用者以進行容量規劃
* 檢測異常使用模式或濫用行為
* 為終端使用者建構基於使用量的計費

### 活動匯出 API

依使用者過濾查詢使用記錄：

```bash theme={null}
curl "https://api.arouter.ai/v1/activity?user=user_12345&limit=100" \
  -H "Authorization: Bearer lr_live_xxxx"
```

***

## 使用案例

### 按使用者成本分攤

追蹤服務每位客戶的實際成本：

```typescript theme={null}
// 傳遞客戶 ID
const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.6",
  messages: conversation,
  user: `customer_${customerId}`,
});

// 之後：查詢活動匯出以取得每位客戶的總成本
```

### 濫用檢測

按使用者監控異常使用模式：

```python theme={null}
# 每位使用者使用自己的識別碼
response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[{"role": "user", "content": user_message}],
    user=f"app_user_{user.id}",
)
```

### 多租戶應用

在多租戶 SaaS 應用中，傳遞組織或租戶 ID：

```typescript theme={null}
const response = await client.chat.completions.create({
  model: "google/gemini-2.5-flash",
  messages: messages,
  user: `org_${organizationId}`,
});
```

***

## 注意事項

* `user` 欄位是選填的。不包含此欄位的請求仍會在 API Key 的彙總使用量下被追蹤。
* 使用者 ID 以不透明字串形式儲存。ARouter 不驗證、解析或解讀其格式。
* 使用者追蹤資料包含在[活動匯出](/zh-Hant/guides/administration/activity-export)記錄中。
* 團隊層級的使用控制請參閱[組織管理](/zh-Hant/guides/administration/organization-management)。