75 lines
3.0 KiB
Plaintext
75 lines
3.0 KiB
Plaintext
---
|
||
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)
|