BridgeAI 后端 API 基于 FastAPI 构建，所有接口均以 /api/v1 为前缀。
支持两种认证方式（二选一）：
-
JWT Bearer Token -- 通过登录获取
Authorization: Bearer <token> -
API Key -- 通过管理后台创建
X-API-Key: <api_key>
需要在请求头中携带租户 ID：
X-Tenant-Id: <tenant_id>
所有接口返回统一的 JSON 格式：
{
"code": 200,
"message": "success",
"data": { ... }
}错误响应：
{
"code": 400,
"message": "错误描述",
"data": null
}列表接口统一使用分页格式：
{
"code": 200,
"message": "success",
"data": {
"items": [...],
"total": 100,
"page": 1,
"size": 20,
"pages": 5
}
}分页参数：
page-- 页码，从 1 开始，默认 1size-- 每页数量，默认 20，最大 100
无需认证
请求体：
{
"username": "admin",
"email": "1178672658@qq.com",
"password": "your_password"
}响应：
{
"code": 200,
"message": "success",
"data": {
"id": "uuid",
"username": "admin",
"email": "1178672658@qq.com",
"role": "user",
"tenant_id": "uuid"
}
}无需认证
请求体：
{
"username": "admin",
"password": "your_password"
}响应：
{
"code": 200,
"message": "success",
"data": {
"access_token": "eyJ...",
"token_type": "bearer",
"user": {
"id": "uuid",
"username": "admin",
"role": "user"
}
}
}
需要认证
请求体：
{
"message": "你好，请帮我分析一下销售数据",
"agent_id": "uuid (可选)",
"conversation_id": "uuid (可选，不传则创建新会话)",
"model": "deepseek-chat (可选)",
"temperature": 0.7,
"max_tokens": 4096,
"stream": true,
"knowledge_base_id": "uuid (可选)"
}{
"code": 200,
"message": "success",
"data": {
"conversation_id": "uuid",
"content": "AI 回复内容",
"model_used": "deepseek-chat",
"token_input": 150,
"token_output": 300
}
}返回 SSE (Server-Sent Events) 流，事件类型：
| 事件类型 | 说明 | 数据格式 |
|---|---|---|
meta |
首个事件，包含会话 ID | {"type": "meta", "conversation_id": "uuid"} |
content |
文本块 | {"type": "content", "content": "文字"} |
tool_call |
工具调用 | {"type": "tool_call", "tool_name": "...", "arguments": {...}} |
tool_result |
工具结果 | {"type": "tool_result", "tool_name": "...", "result": {...}} |
analysis |
上下文分析 | {"type": "analysis", "intent": "...", "emotion": "..."} |
error |
错误 | {"type": "error", "content": "错误信息"} |
done |
流结束 | {"type": "done"} |
需要认证
请求体：
{
"rating": 5,
"feedback": "回答非常准确 (可选)"
}评分范围 1-5，评分 >= 4 的对话会自动进入 Few-shot 学习池。
请求体：
{
"name": "客服助手",
"description": "智能客服机器人",
"system_prompt": "你是一个专业的客服助手...",
"model_config": {
"provider": "deepseek",
"model": "deepseek-chat",
"temperature": 0.7,
"max_tokens": 4096
},
"tools": ["connector-uuid-1", "connector-uuid-2"],
"knowledge_base_id": "uuid (可选)",
"plugins": ["ecommerce"]
}查询参数：page, size
请求体同创建，所有字段可选。
请求体：
{
"name": "业务数据库",
"description": "公司 MySQL 主库",
"connector_type": "mysql",
"endpoint_url": "mysql://user:pass@host:3306/dbname",
"auth_config": {},
"config": {},
"capabilities": ["query", "execute"]
}支持的 connector_type：
mysql/postgresql/database-- 数据库连接器http_api/http-- 通用 HTTP API 连接器feishu/lark-- 飞书连接器
响应：
{
"code": 200,
"message": "连接测试成功",
"data": { "healthy": true }
}响应：
{
"code": 200,
"data": [
{
"name": "query_table",
"description": "查询数据库表",
"parameters": { ... }
}
]
}请求体：
{
"tool_name": "query_table",
"arguments": {
"sql": "SELECT * FROM orders LIMIT 10"
}
}响应：
{
"code": 200,
"data": {
"success": true,
"data": [...],
"error": null,
"duration_ms": 45
}
}请求体：
{
"name": "产品文档",
"description": "公司产品使用手册",
"embedding_model": "bge-m3",
"chunk_size": 500,
"chunk_overlap": 50
}Content-Type: multipart/form-data
表单字段：
file-- 文档文件（支持 PDF、DOCX、MD、TXT）
上传后文档会在后台异步解析、切分、向量化。通过文档详情接口查询处理状态。
请求体：
{
"query": "如何配置单点登录？",
"top_k": 5
}响应：
{
"code": 200,
"data": {
"query": "如何配置单点登录？",
"total": 3,
"results": [
{
"chunk_id": "uuid",
"content": "文档片段内容...",
"similarity": 0.89,
"chunk_index": 5,
"document_id": "uuid"
}
]
}
}企业微信消息推送回调端点，支持 GET（验签）和 POST（消息处理）。
钉钉机器人消息回调端点。
无需认证
响应：
{
"code": 200,
"data": {
"status": "healthy",
"database": "connected",
"redis": "connected"
}
}无需认证
需要认证
返回当前租户的统计数据：对话数、消息数、Agent 数、日使用量、意图分布等。
需要认证
查询参数：page, size, action, user_id, start_date, end_date
需要认证
查询参数：start_date, end_date, group_by
| HTTP 状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证或认证过期 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用（连接器断开等） |