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

# 会话 AI 积分限额

> 使用 sessionLimits 为 Copilot 会话设置 AI 积分限额，并处理与限额相关的事件以及限额耗尽时的确认提示。

使用 `sessionLimits` 可以为 Copilot 会话的当前计费周期设置一个软性的 AI 积分限额。创建会话和恢复会话时都可以设置。

## 设置限额

将限额传给 `SessionLimitsConfig` 的 `maxAiCredits`。用量会在每次模型调用完成后检查，因此单次响应可能会超出设定值。一旦超出限额，运行时会阻止下一次模型调用。

```php theme={null}
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\ResumeSessionConfig;
use Revolution\Copilot\Types\Rpc\SessionLimitsConfig;
use Revolution\Copilot\Types\SessionConfig;

Copilot::start(function (CopilotSession $session) {
    $session->sendAndWait(prompt: 'Tell me something about Laravel.');
}, config: new SessionConfig(
    sessionLimits: new SessionLimitsConfig(maxAiCredits: 30.0),
));

Copilot::client()->resumeSession(
    'existing-session-id',
    new ResumeSessionConfig(
        sessionLimits: new SessionLimitsConfig(maxAiCredits: 30.0),
    ),
);
```

`SessionConfig` 和 `ResumeSessionConfig` 的 `sessionLimits` 都可以接受 `SessionLimitsConfig` 实例或数组。

## 限额事件

监听会话事件，即可在限额发生变化时做出响应，并在达到限额时提示用户。

| 事件 | 触发时机 | 主要数据 |
| - | - | - |
| `session.session_limits_changed` (`SessionEventType::SESSION_SESSION_LIMITS_CHANGED`) | 会话的有效限额发生变化时。如果 `sessionLimits` 为 `null`，则表示不设限额。 | `sessionLimits.maxAiCredits`（可选） |
| `session.usage_checkpoint` (`SessionEventType::SESSION_USAGE_CHECKPOINT`) | 运行时为恢复或计费记录累计用量时。 | `totalNanoAiu`、`totalPremiumRequests`（可选） |
| `session_limits_exhausted.requested` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED`) | 达到限额，需要用户做出决定后会话才能继续时。 | `requestId`、`maxAiCredits`、`usedAiCredits` |
| `session_limits_exhausted.completed` (`SessionEventType::SESSION_LIMITS_EXHAUSTED_COMPLETED`) | 限额耗尽的确认提示已处理完毕时。 | `requestId`、`response.action`、`response.additionalAiCredits`（可选）、`response.maxAiCredits`（可选） |

例如，收到 `SESSION_LIMITS_EXHAUSTED_REQUESTED` 时，可以使用事件数据显示确认界面。

```php theme={null}
use Revolution\Copilot\Enums\SessionEventType;
use Revolution\Copilot\Types\SessionEvent;

$session->on(function (SessionEvent $event): void {
    if ($event->is(SessionEventType::SESSION_LIMITS_EXHAUSTED_REQUESTED)) {
        $requestId = $event->data['requestId'];
        $maxAiCredits = $event->data['maxAiCredits'];
        $usedAiCredits = $event->data['usedAiCredits'];

        // 使用 $requestId 显示确认界面
    }
});
```

## 响应限额耗尽

使用 `handlePendingSessionLimitsExhausted()` 将用户的选择发送回运行时。将 `action` 设置为 `SessionLimitsExhaustedResponseAction` 的某个 case。

```php theme={null}
use Revolution\Copilot\Enums\SessionLimitsExhaustedResponseAction;
use Revolution\Copilot\Types\Rpc\UIHandlePendingSessionLimitsExhaustedRequest;
use Revolution\Copilot\Types\Rpc\UISessionLimitsExhaustedResponse;

$session->rpc()->ui()->handlePendingSessionLimitsExhausted(
    new UIHandlePendingSessionLimitsExhaustedRequest(
        requestId: $requestId,
        response: new UISessionLimitsExhaustedResponse(
            action: SessionLimitsExhaustedResponseAction::Add,
            additionalAiCredits: 10.0,
        ),
    ),
);
```

可用的 action 如下：

* `Add`：在当前限额基础上增加指定的 AI 积分。需设置 `additionalAiCredits`。
* `Set`：将限额更改为新的绝对值。需设置 `maxAiCredits`。
* `Unset`：移除会话限额。
* `Cancel`：取消被阻止的模型请求，不更改限额。

> [!WARNING]
>
> 使用 `session_limits_exhausted.requested` 和 `session_limits_exhausted.completed` 的限额耗尽确认流程以及相关的响应 API 目前处于实验阶段，将来可能会更改或移除。


## Related topics

- [用于 Laravel AI SDK 的 Amazon Bedrock 驱动](https://kawax.biz/zh-CN/packages/laravel-amazon-bedrock.md)
- [会话恢复](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/resume.md)
- [会话钩子](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/hooks.md)
- [会话生命周期事件](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [会话上下文与过滤](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/session-context.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.