186 lines
3.6 KiB
Markdown
186 lines
3.6 KiB
Markdown
# 智能搜索AI Agent API接口文档
|
||
|
||
## 基础信息
|
||
|
||
- **服务名称**: Intelligent Search AI Agent
|
||
- **版本**: 1.0.0
|
||
- **基础URL**: `域名`
|
||
- **Content-Type**: `application/json`
|
||
|
||
---
|
||
|
||
## 核心接口
|
||
|
||
### 执行搜索
|
||
|
||
#### POST /search
|
||
|
||
执行智能搜索，根据查询返回答案和相关来源。
|
||
|
||
**请求参数**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| query | string | 是 | 搜索查询 |
|
||
| llm_api_key | string | 是 | LLM API密钥（用户的API密钥） |
|
||
| user_id | string | 否 | 用户ID（用于计费回调） |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"query": "什么是人工智能？",
|
||
"llm_api_key": "your-llm-api-key",
|
||
"user_id": "user123"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"query": "什么是人工智能？",
|
||
"answer": "人工智能（AI）是计算机科学的一个分支，致力于创建能够执行通常需要人类智能的任务的系统...",
|
||
"sources": [
|
||
{
|
||
"index": 1,
|
||
"title": "人工智能 - 维基百科",
|
||
"url": "https://zh.wikipedia.org/wiki/人工智能"
|
||
},
|
||
{
|
||
"index": 2,
|
||
"title": "什么是AI？",
|
||
"url": "https://example.com/ai-introduction"
|
||
}
|
||
],
|
||
"confidence": "high",
|
||
"iterations": 2,
|
||
"total_sources": 5,
|
||
"search_queries": [
|
||
"什么是人工智能",
|
||
"AI定义"
|
||
],
|
||
"timestamp": "2024-01-01T00:00:00.000000"
|
||
}
|
||
```
|
||
|
||
**响应字段说明**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| query | string | 原始查询 |
|
||
| answer | string | 生成的答案内容（Markdown格式） |
|
||
| sources | array | 来源列表 |
|
||
| sources[].index | integer | 来源索引 |
|
||
| sources[].title | string | 来源标题 |
|
||
| sources[].url | string | 来源URL |
|
||
| confidence | string | 置信度："high" / "medium" / "low" |
|
||
| iterations | integer | 迭代次数 |
|
||
| total_sources | integer | 参考来源总数 |
|
||
| search_queries | array[string] | 使用的搜索查询列表 |
|
||
| timestamp | string | 时间戳（ISO格式） |
|
||
|
||
**错误响应**:
|
||
|
||
400 Bad Request（参数错误）:
|
||
```json
|
||
{
|
||
"detail": "llm_api_key 是必须的参数"
|
||
}
|
||
```
|
||
|
||
500 Internal Server Error（服务器错误）:
|
||
```json
|
||
{
|
||
"detail": "搜索失败: {错误详情}"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 聊天接口
|
||
|
||
#### POST /chat
|
||
|
||
聊天接口，是 `/search` 接口的别名，功能和参数完全相同。
|
||
|
||
**请求参数**: 与 `/search` 接口相同
|
||
|
||
**请求示例**: 与 `/search` 接口相同
|
||
|
||
**响应示例**: 与 `/search` 接口相同
|
||
|
||
---
|
||
|
||
## 其他接口
|
||
|
||
### 健康检查
|
||
|
||
#### GET /health
|
||
|
||
检查服务健康状态。
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /health
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"pod_name": "search-agent",
|
||
"template_type": "search_agent",
|
||
"configured": true,
|
||
"llm_base_url": "https://api.example.com",
|
||
"llm_model": "xchat52",
|
||
"timestamp": "2024-01-01T00:00:00.000000"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 获取状态
|
||
|
||
#### GET /status
|
||
|
||
获取服务状态信息。
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /status
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"status": "running",
|
||
"pod_name": "search-agent",
|
||
"template_type": "search_agent",
|
||
"configured": true,
|
||
"timestamp": "2024-01-01T00:00:00.000000"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
**重要提示**：
|
||
- 用户只需要传递 `query` 和 `llm_api_key` 参数
|
||
- `llm_base_url`、`llm_model` 等配置参数已通过环境变量在部署时配置，**不需要**在请求中传递
|
||
- `user_id` 为可选参数，用于计费回调
|
||
|
||
**请求参数说明**：
|
||
- `query` - 搜索查询内容（必填）
|
||
- `llm_api_key` - 用户的LLM API密钥（必填）
|
||
- `user_id` - 用户ID（可选）
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| HTTP状态码 | 说明 |
|
||
|-----------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 500 | 服务器内部错误 |
|