f
This commit is contained in:
@@ -1,5 +1,8 @@
|
||||
export default {
|
||||
console: "???",
|
||||
http_api: "HTTP API",
|
||||
openai_compatible: "OpenAI 兼容 SDK",
|
||||
console: "控制台",
|
||||
api_keys: "API Key",
|
||||
streaming: "????",
|
||||
streaming: "流式调用",
|
||||
billing: "计费与财务",
|
||||
};
|
||||
|
||||
@@ -1,26 +1,55 @@
|
||||
---
|
||||
title: API Key 管理
|
||||
sidebarTitle: API Key
|
||||
description: 创建、轮换与权限最佳实践
|
||||
description: 创建、轮换、额度与白名单最佳实践
|
||||
---
|
||||
|
||||
# API Key 管理
|
||||
|
||||
在控制台侧栏 **API Key** 中管理所有调用凭证。创建与管理前需完成 **实名认证**。
|
||||
|
||||
## 创建
|
||||
|
||||
控制台 → **设置 → API Key** → **创建**。建议命名包含环境与用途，例如 `prod-report-agent`。
|
||||
1. 点击 **创建**
|
||||
2. 填写名称（建议包含环境与用途，如 `prod-report-agent`）
|
||||
3. 可选配置：
|
||||
- **可用模型**：限制该 Key 只能调用指定模型
|
||||
- **额度上限 / 剩余额度**：控制总消耗
|
||||
- **过期时间**：到期后 Key 自动失效
|
||||
- **IP 白名单**：仅允许 listed IP 调用（留空表示不限制，生产环境建议配置）
|
||||
|
||||
创建成功后请 **立即复制并保存** 完整密钥；之后列表仅显示脱敏前缀。
|
||||
|
||||
## 鉴权方式
|
||||
|
||||
HTTP 请求头：
|
||||
|
||||
```http
|
||||
Authorization: Bearer <你的 API Key>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
OpenAI SDK 中将该 Key 设为 `apiKey`，`baseURL` 设为 `https://api.haiyushuke.com/v1`（见 [OpenAI 兼容 SDK](/docs/guides/openai_compatible)）。
|
||||
|
||||
## 存储
|
||||
|
||||
- 使用环境变量：`HAIYUSHUKE_API_KEY`
|
||||
- 密钥管理系统（KMS / Vault）中保存，勿提交至 Git
|
||||
- 环境变量：如 `HAIYUSHUKE_API_KEY`
|
||||
- 密钥管理系统（KMS / Vault），勿提交至 Git 或镜像层
|
||||
|
||||
## 轮换流程
|
||||
|
||||
1. 创建新 Key
|
||||
2. 在应用配置中灰度切换
|
||||
3. 确认流量稳定后禁用旧 Key
|
||||
1. 创建新 Key（可先绑定相同模型与 IP 策略）
|
||||
2. 在应用配置中灰度切换
|
||||
3. 观察 **使用记录** 确认旧 Key 无流量后 **禁用** 旧 Key
|
||||
|
||||
## 泄露应急
|
||||
|
||||
若 Key 已泄露：立即 **禁用** 该 Key → 新建 → 排查仓库与 CI 日志是否残留。
|
||||
1. 控制台中 **禁用** 泄露的 Key
|
||||
2. 新建 Key 并更新部署
|
||||
3. 检查 Git 历史、CI 日志、前端 bundle 是否残留
|
||||
4. 若曾未设 IP 白名单，建议新 Key 启用白名单
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [快速开始](/docs/getting-started)
|
||||
- [常见问题：401 与 Key](/docs/faq#返回-401-unauthorized)
|
||||
|
||||
43
content/guides/billing.mdx
Normal file
43
content/guides/billing.mdx
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: 计费与财务
|
||||
sidebarTitle: 计费与财务
|
||||
description: 充值、账单、使用记录与发票说明
|
||||
---
|
||||
|
||||
# 计费与财务
|
||||
|
||||
模型调用按 **输入 token / 输出 token**（或模型广场标注的计价单位）从账户 **余额** 扣费。请在控制台 **财务** 菜单中查看与充值。
|
||||
|
||||
## 模块说明
|
||||
|
||||
| 菜单 | 作用 |
|
||||
| --- | --- |
|
||||
| 财务总览 | 当前余额、近期消耗与快捷入口 |
|
||||
| 账户充值 | 在线充值（需先完成实名认证） |
|
||||
| 充值明细 | 充值订单与到账状态 |
|
||||
| 费用账单 | 按月汇总模型与相关服务费用 |
|
||||
| 使用记录 | 单次调用的模型、用量与扣费明细 |
|
||||
| 发票开具 | 对已结清账单申请增值税发票（需实名认证） |
|
||||
|
||||
## 计费逻辑（概要）
|
||||
|
||||
1. 发起 API 或体验中心调用前，账户需有足够余额。
|
||||
2. 请求成功后，系统按模型定价与实际上下 token 用量记账。
|
||||
3. 余额不足时，网关可能返回 **402 Payment Required**（业务码 `INSUFFICIENT_BALANCE`），请先 [账户充值](https://console.haiyushuke.com/finance/recharge)。
|
||||
|
||||
具体单价以 **模型广场** 各模型卡片为准；促销或「特惠」模型以控制台标注为准。
|
||||
|
||||
## 余额告警
|
||||
|
||||
在 **账户中心 → 通知管理** 中可配置余额阈值与通知方式，避免生产流量因余额耗尽中断。
|
||||
|
||||
## 对账建议
|
||||
|
||||
- 日常：用 **使用记录** 按模型、时间筛选，与业务日志中的 request id 对照。
|
||||
- 月度：导出或查看 **费用账单**，与财务系统对账。
|
||||
- 企业客户：如需明细导出、合同价或专票流程，请通过 [联系我们](/#contact) 联系商务。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [控制台使用指南](/docs/guides/console)
|
||||
- [常见问题：余额与账单](/docs/faq#余额不足还能调用吗)
|
||||
@@ -8,23 +8,38 @@ description: 控制台主要功能与导航说明
|
||||
|
||||
控制台地址：[https://console.haiyushuke.com](https://console.haiyushuke.com)
|
||||
|
||||
## 主要模块
|
||||
## 侧栏模块
|
||||
|
||||
1. **概览**：用量、余额与近期调用趋势
|
||||
2. **模型广场**：浏览可用模型、定价与能力说明
|
||||
3. **API Key**：创建、轮换、禁用密钥
|
||||
4. **调用日志**（若已开通）：按时间筛选请求与错误
|
||||
5. **账单**：充值、发票与明细导出
|
||||
| 模块 | 说明 |
|
||||
| --- | --- |
|
||||
| 数据看板 | 用量与账户概览（持续完善中） |
|
||||
| 模型广场 | 浏览国内模型、价格、能力标签；复制模型 ID；**接入文档** 跳转官网 [工具接入](/docs/integrations/overview) |
|
||||
| 体验中心 | 登录且实名认证后，在线对话试调用 |
|
||||
| API Key | 创建与管理调用凭证、额度与 IP 白名单 |
|
||||
| 开发文档 | 跳转至官网 [文档中心](/docs) |
|
||||
| 财务 | 总览、充值、充值明细、账单、使用记录、发票 |
|
||||
| 账户中心 | 账号设置、实名认证、通知管理 |
|
||||
|
||||
侧栏底部 **常见问题** 同样跳转至官网文档 [FAQ](/docs/faq)；**在线客服** 打开企业微信客服。
|
||||
|
||||
## 推荐工作流
|
||||
|
||||
1. 创建 API Key
|
||||
2. 在模型广场选择目标模型
|
||||
3. 使用 SDK 或 cURL 完成联调
|
||||
4. 在概览与调用日志中核对用量
|
||||
1. 完成 **实名认证**
|
||||
2. **账户充值**（若账户需预付费）
|
||||
3. 在 **模型广场** 选定模型，在 **体验中心** 验证效果
|
||||
4. 在 **API Key** 创建密钥并限制模型范围
|
||||
5. 在 Cursor 等工具或业务服务中配置 `baseURL` 与 Key，见 [工具接入概览](/docs/integrations/overview)
|
||||
6. 在 **使用记录** / **费用账单** 中核对用量
|
||||
|
||||
## 权限与安全
|
||||
|
||||
- 为不同环境（开发 / 预发 / 生产）使用不同 Key
|
||||
- 定期轮换 Key；泄露后立即 **禁用** 并新建
|
||||
- 生产环境勿将 Key 写入前端 bundle
|
||||
- 开发、预发、生产使用 **不同 API Key**，便于泄露时单独轮换
|
||||
- 生产环境勿将 Key 写入前端静态资源或公开仓库
|
||||
- 为 Key 配置 **IP 白名单** 可降低密钥泄露风险
|
||||
- Key 泄露后：立即 **禁用** → 新建 Key → 排查 CI 与日志是否残留
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [API Key 管理](/docs/guides/api_keys)
|
||||
- [计费与财务](/docs/guides/billing)
|
||||
- [工具接入概览](/docs/integrations/overview)
|
||||
|
||||
95
content/guides/http_api.mdx
Normal file
95
content/guides/http_api.mdx
Normal file
@@ -0,0 +1,95 @@
|
||||
---
|
||||
title: HTTP API 调用
|
||||
sidebarTitle: HTTP API
|
||||
description: RESTful Chat Completions 接口说明
|
||||
---
|
||||
|
||||
# HTTP API 调用
|
||||
|
||||
海宇数科网关提供与 OpenAI 兼容的 **RESTful HTTP API**，适用于任意编程语言、curl、API 网关或服务 mesh，无需安装专用 SDK。
|
||||
|
||||
## 基本信息
|
||||
|
||||
| 项目 | 值 |
|
||||
| --- | --- |
|
||||
| Base URL | `https://api.haiyushuke.com/v1` |
|
||||
| 对话补全 | `POST /chat/completions` |
|
||||
| Content-Type | `application/json` |
|
||||
| 鉴权 | `Authorization: Bearer <API_KEY>` |
|
||||
|
||||
API Key 在控制台 **API Key** 创建；详见 [API Key 管理](/docs/guides/api_keys)。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl https://api.haiyushuke.com/v1/chat/completions \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "deepseek-chat",
|
||||
"messages": [
|
||||
{"role": "system", "content": "你是简洁的企业助手。"},
|
||||
{"role": "user", "content": "什么是 Token？"}
|
||||
],
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 1024
|
||||
}'
|
||||
```
|
||||
|
||||
## 请求体常用字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `model` | string | **必填**。控制台模型广场中的 ID |
|
||||
| `messages` | array | **必填**。`role`：`system` / `user` / `assistant` |
|
||||
| `temperature` | number | 可选，采样随机性，常见 0–2 |
|
||||
| `max_tokens` | integer | 可选，限制本次最大生成 token |
|
||||
| `stream` | boolean | 可选，`true` 时返回 SSE，见 [流式调用](/docs/guides/streaming) |
|
||||
|
||||
部分模型支持更多参数（如 `top_p`、`stop` 等），与 OpenAI 兼容子集一致；不支持的字段可能被忽略或返回参数错误。
|
||||
|
||||
## 响应结构（非流式）
|
||||
|
||||
成功时 HTTP **200**，JSON 主体包含：
|
||||
|
||||
- `id`：请求标识
|
||||
- `choices[].message.content`：模型回复文本
|
||||
- `usage`：token 统计，用于对账，见 [核心概念](/docs/concepts/overview#token-与-usage)
|
||||
|
||||
```json
|
||||
{
|
||||
"choices": [
|
||||
{
|
||||
"message": { "role": "assistant", "content": "..." },
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 12,
|
||||
"completion_tokens": 48,
|
||||
"total_tokens": 60
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 错误与 HTTP 状态码
|
||||
|
||||
| 状态 | 常见原因 |
|
||||
| --- | --- |
|
||||
| 401 | Key 无效、过期、禁用或 Authorization 格式错误 |
|
||||
| 402 | 账户余额不足（`INSUFFICIENT_BALANCE`） |
|
||||
| 403 | Key 无该模型权限、IP 不在白名单等 |
|
||||
| 429 | 限流，需退避重试 |
|
||||
| 4xx/5xx | 参数错误、模型不存在或上游异常，见响应 body 中的 `message` / `code` |
|
||||
|
||||
更多排查见 [常见问题](/docs/faq)。
|
||||
|
||||
## 流式响应
|
||||
|
||||
设置 `"stream": true` 后，响应为 **SSE** 增量块，格式与 OpenAI 流式兼容。客户端须持续读取直至 `[DONE]`，并处理断线重试。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [OpenAI SDK 兼容](/docs/guides/openai_compatible)
|
||||
- [快速开始](/docs/getting-started)
|
||||
- [工具接入概览](/docs/integrations/overview)（Cursor、Claude Code 等）
|
||||
99
content/guides/openai_compatible.mdx
Normal file
99
content/guides/openai_compatible.mdx
Normal file
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: OpenAI 兼容 SDK
|
||||
sidebarTitle: OpenAI 兼容 SDK
|
||||
description: 使用 OpenAI 官方 SDK 对接海宇数科网关（协议兼容，模型为国内 ID）
|
||||
---
|
||||
|
||||
# OpenAI SDK 兼容
|
||||
|
||||
若您已有基于 **OpenAI 官方 SDK** 的应用，迁移到海宇数科通常只需两步：
|
||||
|
||||
1. 将 `baseURL`（或 `base_url`）改为 `https://api.haiyushuke.com/v1`
|
||||
2. 将 `apiKey` 改为在海宇控制台创建的 **API Key**
|
||||
|
||||
协议兼容 **Chat Completions**（`client.chat.completions.create`），便于零学习成本切换。
|
||||
|
||||
## 环境变量（推荐）
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
export HAIYUSHUKE_API_KEY="sk-..."
|
||||
export HAIYUSHUKE_BASE_URL="https://api.haiyushuke.com/v1"
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
$env:HAIYUSHUKE_API_KEY="sk-..."
|
||||
$env:HAIYUSHUKE_BASE_URL="https://api.haiyushuke.com/v1"
|
||||
```
|
||||
|
||||
## Node.js
|
||||
|
||||
安装依赖：
|
||||
|
||||
```bash
|
||||
npm install openai
|
||||
```
|
||||
|
||||
```ts
|
||||
import OpenAI from "openai";
|
||||
|
||||
const client = new OpenAI({
|
||||
apiKey: process.env.HAIYUSHUKE_API_KEY,
|
||||
baseURL: process.env.HAIYUSHUKE_BASE_URL ?? "https://api.haiyushuke.com/v1",
|
||||
});
|
||||
|
||||
const completion = await client.chat.completions.create({
|
||||
model: "deepseek-chat",
|
||||
messages: [{ role: "user", content: "Hello" }],
|
||||
});
|
||||
|
||||
console.log(completion.choices[0]?.message?.content);
|
||||
```
|
||||
|
||||
## Python
|
||||
|
||||
安装依赖：
|
||||
|
||||
```bash
|
||||
pip install openai
|
||||
```
|
||||
|
||||
```python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key=os.environ["HAIYUSHUKE_API_KEY"],
|
||||
base_url=os.environ.get("HAIYUSHUKE_BASE_URL", "https://api.haiyushuke.com/v1"),
|
||||
)
|
||||
|
||||
resp = client.chat.completions.create(
|
||||
model="deepseek-chat",
|
||||
messages=[{"role": "user", "content": "Hello"}],
|
||||
)
|
||||
print(resp.choices[0].message.content)
|
||||
```
|
||||
|
||||
## 流式
|
||||
|
||||
与 OpenAI 相同，设置 `stream=True` / `stream: true`，详见 [流式调用](/docs/guides/streaming)。
|
||||
|
||||
## LangChain 等框架
|
||||
|
||||
在 LangChain 中配置自定义 `baseURL` 与 API Key 即可指向海宇网关（具体类名随 LangChain 版本而异，原则与上文一致）。模型名填控制台 **模型 ID**。
|
||||
|
||||
## 与直连 OpenAI 的差异
|
||||
|
||||
| 项目 | 说明 |
|
||||
| --- | --- |
|
||||
| 模型名 | 使用海宇 **模型广场 ID**，非 OpenAI 原站名称（若不同） |
|
||||
| 账号与计费 | 海宇控制台余额与 **使用记录**，与 OpenAI 账单无关 |
|
||||
| 能力边界 | 以各模型在海宇侧实际上线能力为准（工具调用、多模态等） |
|
||||
| 密钥 | 必须使用 **API Key**，不能使用控制台登录 JWT |
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [HTTP API 调用](/docs/guides/http_api)
|
||||
- [工具接入概览](/docs/integrations/overview)
|
||||
- [API Key 管理](/docs/guides/api_keys)
|
||||
@@ -6,7 +6,7 @@ description: SSE 流式输出接入说明
|
||||
|
||||
# 流式调用
|
||||
|
||||
在请求体中设置 `"stream": true`，服务端以 SSE 形式返回增量内容。
|
||||
在请求体中设置 `"stream": true`，服务端以 SSE 形式返回增量内容。协议与 OpenAI 流式兼容；HTTP 基础见 [HTTP API](/docs/guides/http_api)。
|
||||
|
||||
## cURL
|
||||
|
||||
@@ -14,14 +14,14 @@ description: SSE 流式输出接入说明
|
||||
curl https://api.haiyushuke.com/v1/chat/completions \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"gpt-4o-mini","stream":true,"messages":[{"role":"user","content":"写一首四句诗"}]}'
|
||||
-d '{"model":"deepseek-chat","stream":true,"messages":[{"role":"user","content":"写一首四句诗"}]}'
|
||||
```
|
||||
|
||||
## OpenAI SDK（Node）
|
||||
|
||||
```ts
|
||||
const stream = await client.chat.completions.create({
|
||||
model: "gpt-4o-mini",
|
||||
model: "deepseek-chat",
|
||||
stream: true,
|
||||
messages: [{ role: "user", content: "你好" }],
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user