docs(api-guide): 更新API文档至生产配置 + 重新生成PDF
主要变更： - 模型名称: xiaoai-engine-v1 → xiaoai-chat-v1 (对话) / xiaoai-embed-v1 (向量化) 与实际数据库配置的 modelAlias 保持一致 - model 参数说明: 明确区分对话接口和向量化接口使用不同模型名 - SDK 安装: 按接口类型（Messages / Chat Completions / Embeddings）分别说明 - FAQ: 补充两个模型名的对应关系 - 所有代码示例中的 model 值已同步更新 - 重新生成 PDF 文件 当前生产 API Key 配置： - Anthropic Messages → modelAlias: xiaoai-chat-v1 - OpenAI Chat Completions → modelAlias: xiaoai-chat-v1 - OpenAI Embeddings → modelAlias: xiaoai-embed-v1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
4ef5fce924
commit
a914a80fc3
|
|
@ -0,0 +1,459 @@
|
|||
# 小艾引擎 API 开发文档
|
||||
|
||||
**版本**: v1.0
|
||||
**更新日期**: 2026-02-26
|
||||
**基础地址**: `https://api1.szaiai.com`
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
小艾引擎 API 提供强大的大语言模型能力，支持对话补全、流式输出和文本向量化。接口兼容主流 SDK，开发者可快速集成。
|
||||
|
||||
### 接入信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 基础地址 | `https://api1.szaiai.com` |
|
||||
| 认证方式 | API Key（由管理员分配） |
|
||||
| 请求格式 | JSON |
|
||||
| 字符编码 | UTF-8 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 认证
|
||||
|
||||
所有请求必须携带 API Key，支持两种方式：
|
||||
|
||||
**方式一：X-Api-Key 请求头**
|
||||
```
|
||||
X-Api-Key: sk-gw-your-key-here
|
||||
```
|
||||
|
||||
**方式二：Bearer Token（兼容 OpenAI SDK）**
|
||||
```
|
||||
Authorization: Bearer sk-gw-your-key-here
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. API 接口
|
||||
|
||||
### 3.1 对话补全（Messages）
|
||||
|
||||
创建一轮对话，模型根据消息上下文生成回复。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST /v1/messages
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| model | string | 是 | 模型名称，填写管理员提供的值（如 `xiaoai-chat-v1`） |
|
||||
| messages | array | 是 | 对话消息列表 |
|
||||
| max_tokens | integer | 是 | 最大生成 token 数（建议 1024-4096） |
|
||||
| stream | boolean | 否 | 是否启用流式输出，默认 false |
|
||||
| temperature | number | 否 | 采样温度 0-1，默认 1。越低越确定 |
|
||||
| top_p | number | 否 | 核采样概率 0-1 |
|
||||
| stop_sequences | array | 否 | 停止序列列表 |
|
||||
| system | string | 否 | 系统提示词，设定模型角色和行为 |
|
||||
|
||||
**messages 格式**
|
||||
|
||||
```json
|
||||
[
|
||||
{"role": "user", "content": "你好，请介绍一下你自己"},
|
||||
{"role": "assistant", "content": "你好！我是小艾引擎..."},
|
||||
{"role": "user", "content": "你能做什么？"}
|
||||
]
|
||||
```
|
||||
|
||||
支持的 role：
|
||||
- `user` — 用户消息
|
||||
- `assistant` — 助手消息（用于多轮对话上下文）
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "xiaoai-chat-v1",
|
||||
"id": "msg-a1b2c3d4e5f6...",
|
||||
"type": "message",
|
||||
"role": "assistant",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "你好！我是小艾引擎，一个强大的AI助手..."
|
||||
}
|
||||
],
|
||||
"stop_reason": "end_turn",
|
||||
"usage": {
|
||||
"input_tokens": 15,
|
||||
"output_tokens": 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**响应字段说明**
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| model | 模型名称 |
|
||||
| id | 请求唯一标识 |
|
||||
| content | 回复内容数组，每项包含 type 和 text |
|
||||
| stop_reason | 停止原因：end_turn（正常结束）、max_tokens（达到上限）、stop_sequence |
|
||||
| usage.input_tokens | 输入消耗的 token 数 |
|
||||
| usage.output_tokens | 输出消耗的 token 数 |
|
||||
|
||||
---
|
||||
|
||||
### 3.2 对话补全（Chat Completions，OpenAI 兼容）
|
||||
|
||||
兼容 OpenAI Chat Completions 格式，方便从 OpenAI SDK 迁移。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST /v1/chat/completions
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| model | string | 是 | 模型名称 |
|
||||
| messages | array | 是 | 对话消息列表 |
|
||||
| max_tokens | integer | 否 | 最大生成 token 数 |
|
||||
| stream | boolean | 否 | 是否流式输出 |
|
||||
| temperature | number | 否 | 采样温度 0-2 |
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "cmpl-a1b2c3d4e5f6...",
|
||||
"object": "chat.completion",
|
||||
"model": "xiaoai-chat-v1",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "你好！有什么可以帮助你的吗？"
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"completion_tokens": 15,
|
||||
"total_tokens": 25
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.3 文本向量化（Embeddings）
|
||||
|
||||
将文本转换为向量表示，用于语义搜索、聚类等场景。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST /v1/embeddings
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| model | string | 是 | 模型名称 |
|
||||
| input | string 或 array | 是 | 待向量化的文本（或文本数组） |
|
||||
| encoding_format | string | 否 | 返回格式：float（默认）或 base64 |
|
||||
|
||||
**响应示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"object": "list",
|
||||
"model": "xiaoai-embed-v1",
|
||||
"data": [
|
||||
{
|
||||
"object": "embedding",
|
||||
"index": 0,
|
||||
"embedding": [0.0023, -0.0091, 0.0152, ...]
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 8,
|
||||
"total_tokens": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 流式输出（Streaming）
|
||||
|
||||
流式模式下，模型逐步返回生成内容，适合实时展示场景。设置 `stream: true` 即可启用。
|
||||
|
||||
响应格式为 Server-Sent Events (SSE)，每行以 `data: ` 开头：
|
||||
|
||||
```
|
||||
event: message_start
|
||||
data: {"type":"message_start","message":{"model":"xiaoai-chat-v1",...}}
|
||||
|
||||
event: content_block_delta
|
||||
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"你好"}}
|
||||
|
||||
event: content_block_delta
|
||||
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"！"}}
|
||||
|
||||
event: message_stop
|
||||
data: {"type":"message_stop"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 错误处理
|
||||
|
||||
**错误响应格式**
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "error_type",
|
||||
"message": "错误详细描述"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**常见错误码**
|
||||
|
||||
| HTTP 状态码 | 错误类型 | 说明 |
|
||||
|------------|---------|------|
|
||||
| 400 | invalid_request_error | 请求参数错误（如 JSON 格式无效） |
|
||||
| 401 | authentication_error | API Key 无效或缺失 |
|
||||
| 403 | permission_error | 权限不足（如 Key 已禁用或过期） |
|
||||
| 429 | rate_limit_error | 请求频率超限，请降低调用频率 |
|
||||
| 502 | upstream_error | 服务暂时不可用，请稍后重试 |
|
||||
|
||||
**建议的重试策略**：遇到 429 或 502 错误时，采用指数退避（1s, 2s, 4s...）重试，最多重试 3 次。
|
||||
|
||||
---
|
||||
|
||||
## 6. 代码示例
|
||||
|
||||
### 6.1 Python — 对话补全
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic(
|
||||
api_key="sk-gw-your-key-here",
|
||||
base_url="https://api1.szaiai.com"
|
||||
)
|
||||
|
||||
response = client.messages.create(
|
||||
model="xiaoai-chat-v1",
|
||||
max_tokens=1024,
|
||||
messages=[
|
||||
{"role": "user", "content": "请用三句话介绍人工智能"}
|
||||
]
|
||||
)
|
||||
|
||||
print(response.content[0].text)
|
||||
```
|
||||
|
||||
### 6.2 Python — 流式输出
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
|
||||
client = anthropic.Anthropic(
|
||||
api_key="sk-gw-your-key-here",
|
||||
base_url="https://api1.szaiai.com"
|
||||
)
|
||||
|
||||
with client.messages.stream(
|
||||
model="xiaoai-chat-v1",
|
||||
max_tokens=1024,
|
||||
messages=[{"role": "user", "content": "写一首关于春天的诗"}]
|
||||
) as stream:
|
||||
for text in stream.text_stream:
|
||||
print(text, end="", flush=True)
|
||||
```
|
||||
|
||||
### 6.3 Python — OpenAI 兼容模式
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key="sk-gw-your-key-here",
|
||||
base_url="https://api1.szaiai.com/v1"
|
||||
)
|
||||
|
||||
response = client.chat.completions.create(
|
||||
model="xiaoai-chat-v1",
|
||||
messages=[
|
||||
{"role": "user", "content": "什么是机器学习？"}
|
||||
]
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
|
||||
### 6.4 Node.js
|
||||
|
||||
```javascript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
|
||||
const client = new Anthropic({
|
||||
apiKey: "sk-gw-your-key-here",
|
||||
baseURL: "https://api1.szaiai.com",
|
||||
});
|
||||
|
||||
const response = await client.messages.create({
|
||||
model: "xiaoai-chat-v1",
|
||||
max_tokens: 1024,
|
||||
messages: [{ role: "user", content: "你好" }],
|
||||
});
|
||||
|
||||
console.log(response.content[0].text);
|
||||
```
|
||||
|
||||
### 6.5 cURL
|
||||
|
||||
```bash
|
||||
curl https://api1.szaiai.com/v1/messages \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-Api-Key: sk-gw-your-key-here" \
|
||||
-d '{
|
||||
"model": "xiaoai-chat-v1",
|
||||
"max_tokens": 1024,
|
||||
"messages": [
|
||||
{"role": "user", "content": "你好"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### 6.6 文本向量化
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
api_key="sk-gw-your-key-here",
|
||||
base_url="https://api1.szaiai.com/v1"
|
||||
)
|
||||
|
||||
response = client.embeddings.create(
|
||||
model="xiaoai-embed-v1",
|
||||
input="人工智能是计算机科学的一个分支"
|
||||
)
|
||||
|
||||
print(f"向量维度: {len(response.data[0].embedding)}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 多轮对话
|
||||
|
||||
实现多轮对话需要将历史消息传入 messages 数组：
|
||||
|
||||
```python
|
||||
messages = [
|
||||
{"role": "user", "content": "我叫小明"},
|
||||
{"role": "assistant", "content": "你好小明！很高兴认识你。"},
|
||||
{"role": "user", "content": "我叫什么名字？"}
|
||||
]
|
||||
|
||||
response = client.messages.create(
|
||||
model="xiaoai-chat-v1",
|
||||
max_tokens=256,
|
||||
messages=messages
|
||||
)
|
||||
# 模型会回答"你叫小明"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 系统提示词
|
||||
|
||||
通过 system 参数设定模型的角色和行为：
|
||||
|
||||
```python
|
||||
response = client.messages.create(
|
||||
model="xiaoai-chat-v1",
|
||||
max_tokens=1024,
|
||||
system="你是一位专业的法律顾问，用通俗易懂的语言解答法律问题。",
|
||||
messages=[
|
||||
{"role": "user", "content": "租房合同到期后房东不退押金怎么办？"}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 使用限制
|
||||
|
||||
| 限制项 | 默认值 | 说明 |
|
||||
|--------|--------|------|
|
||||
| 请求频率 | 60 次/分钟 | 可按需调整，联系管理员 |
|
||||
| 单次请求体大小 | 50 MB | 支持大文档、图片 base64 |
|
||||
| max_tokens 上限 | 取决于模型 | 通常 4096-8192 |
|
||||
|
||||
---
|
||||
|
||||
## 10. SDK 安装
|
||||
|
||||
小艾引擎 API 兼容主流 SDK，选择以下任一方式安装：
|
||||
|
||||
**Python — Messages 接口**
|
||||
```bash
|
||||
pip install anthropic
|
||||
```
|
||||
|
||||
**Python — Chat Completions / Embeddings 接口**
|
||||
```bash
|
||||
pip install openai
|
||||
```
|
||||
|
||||
**Node.js — Messages 接口**
|
||||
```bash
|
||||
npm install @anthropic-ai/sdk
|
||||
```
|
||||
|
||||
**Node.js — Chat Completions / Embeddings 接口**
|
||||
```bash
|
||||
npm install openai
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 常见问题
|
||||
|
||||
**Q: model 参数填什么？**
|
||||
A: 填写管理员分配给您的模型名称。对话接口填 `xiaoai-chat-v1`，向量化接口填 `xiaoai-embed-v1`。具体以管理员提供为准。
|
||||
|
||||
**Q: 支持图片输入吗？**
|
||||
A: 支持。在 content 中使用 image 类型的内容块，传入 base64 编码的图片即可。
|
||||
|
||||
**Q: 流式输出和普通模式有什么区别？**
|
||||
A: 流式模式下模型边生成边返回，首个 token 到达更快，适合聊天界面实时显示。普通模式等全部生成完毕后一次性返回。
|
||||
|
||||
**Q: 如何计算费用？**
|
||||
A: 按 input_tokens + output_tokens 计费，具体单价请联系管理员。
|
||||
|
||||
---
|
||||
|
||||
> **技术支持**: 如有问题请联系管理员获取帮助。
|
||||
Binary file not shown.
Loading…
Reference in New Issue