f

content/concepts/_meta.js

@@ -0,0 +1,3 @@
+export default {
+  overview: "核心概念",
+};

content/concepts/overview.mdx

@@ -0,0 +1,74 @@
+---
+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)