hailin
/
iconsulting
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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:
hailin 2026-02-26 02:42:33 -08:00
parent 4ef5fce924
commit a914a80fc3
2 changed files with 459 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

459
docs/api-guide.md Normal file
View File

@ -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 计费，具体单价请联系管理员。
---
> **技术支持**: 如有问题请联系管理员获取帮助。

BIN
docs/api-guide.pdf Normal file
View File

Binary file not shown.