---
title: 核心概念
sidebarTitle: 核心概念
description: Token、上下文窗口、模型 ID 与计费
---

# 核心概念

理解以下概念，有助于控制成本、避免超长报错，并正确对接 [HTTP API](/docs/guides/http_api) 与 [OpenAI SDK](/docs/guides/openai_compatible)。

## Token 与 usage

**Token** 是模型处理文本的基本单位，可粗略理解为「字 / 词」的切分片段。不同模型分词方式不同，**中文、英文、数字、符号** 的 token 数未必与字符数 1:1 对应。

每次成功的 Chat Completions 响应（非流式）通常包含 `usage` 字段，例如：

```json
"usage": {
  "prompt_tokens": 100,
  "completion_tokens": 200,
  "total_tokens": 300
}
```

- **prompt_tokens**：输入侧（含 `messages` 与部分系统开销）  
- **completion_tokens**：模型生成内容  
- 控制台 **使用记录** 与 **费用账单** 按平台计价规则据此扣费  

流式调用结束后，也可能在最后一个 chunk 或汇总接口中提供 usage，以实际返回为准。

## 上下文窗口

**上下文窗口** 指单次请求中，模型能处理的 **最大 token 总量**（通常包括用户输入、历史多轮、模型输出；部分推理模型还包含中间推理 token）。

若对话过长：

1. **超出部分可能被截断**，导致模型「忘记」 earlier 内容  
2. 可能直接返回参数或长度类错误  

**建议：**

- 在 [模型广场](https://console.haiyushuke.com/models) 查看各模型上下文上限  
- 长文档场景优先选用 **长上下文** 模型，或做分段摘要 + RAG  
- 多模态输入（图片、音频等）常有 **更严格的输入限制**，以模型说明为准  

## 模型 ID

**模型 ID** 是 API 中 `model` 字段的字符串，是调用时的唯一标识。

- 必须从 **控制台模型广场** 复制，勿臆造或沿用其他平台的名称  
- API Key 可配置 **可用模型** 子集；请求未授权的 ID 会失败  
- 厂商升级版本时 ID 可能变化（如 `glm-5` → `glm-5.1`），需关注控制台公告  

详见 [工具接入概览](/docs/integrations/overview) 与控制台 **模型广场**。

## API Key 与控制台登录

- **API Key**：用于 `Authorization: Bearer`，调用 **网关 API**  
- **控制台 JWT / Session**：仅用于登录 **console.haiyushuke.com** 管理资源  

二者不可混用。Key 泄露风险高，须 [妥善保管](/docs/guides/api_keys)。

## 余额与扣费

调用前账户需有足够 **余额**（预付费模式）。扣费一般发生在请求成功并完成计量之后；余额不足时返回 **402** / `INSUFFICIENT_BALANCE`。见 [计费与财务](/docs/guides/billing)。

## 统一网关

海宇数科 **统一网关** 对上游多厂商做路由与计量：您面对的是一个 Base URL 与一套 Key 体系，底层模型由平台调度至对应供应商。因此文档与控制台以 **海宇模型 ID** 为准，而非各厂商原站产品名。

## 延伸阅读

- [快速开始](/docs/getting-started)  
- [常见问题](/docs/faq)