MBE API 参考文档

概述

基础信息

Base URL: https://mbe.hi-maker.com (生产环境) / http://localhost:8000 (本地开发)
协议: HTTPS (生产环境强制)
数据格式: JSON
字符编码: UTF-8

请求格式

POST /api/knowledge/create HTTP/1.1
Host: mbe.hi-maker.com
Content-Type: application/json
Authorization: Bearer mbe_sk_xxxxxxxxxxxx

{
    "name": "我的知识库",
    "description": "知识库描述"
}

响应格式

成功响应：

{
    "success": true,
    "data": { ... },
    "message": "操作成功"
}

错误响应：

{
    "success": false,
    "error": "错误信息",
    "code": "ERROR_CODE"
}

认证方式

1. API Key 认证（推荐）

适用于服务端调用，通过开发者门户获取 API Key。

Header 方式：

Authorization: Bearer mbe_sk_xxxxxxxxxxxxxxxxxxxx

或：

X-API-Key: mbe_sk_xxxxxxxxxxxxxxxxxxxx

Query 参数方式：

GET /api/knowledge/?api_key=mbe_sk_xxxxxxxxxxxxxxxxxxxx

2. Device ID 认证

适用于客户端匿名用户，自动创建用户账号。

X-Device-ID: unique_device_identifier

3. JWT Token 认证

适用于已登录用户。

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

知识库 API

创建知识库

创建一个新的知识库。

请求：

POST /admin/knowledge/create
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
name	string	是	知识库名称
description	string	否	知识库描述
language	string	否	语言（auto/zh/en）

请求示例：

{
    "name": "法律咨询知识库",
    "description": "包含常见法律问题解答",
    "language": "zh"
}

响应示例：

{
    "success": true,
    "kb_id": "kb_abc123def456",
    "message": "知识库创建成功"
}

上传文档

上传 PDF/TXT/MD 文件到知识库。

请求：

POST /admin/knowledge/upload/{kb_id}
Content-Type: multipart/form-data
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID（路径参数）
file	file	是	上传的文件

响应示例：

{
    "success": true,
    "kb_id": "kb_abc123def456",
    "message": "文件上传成功",
    "stats": {
        "chunk_count": 156,
        "char_count": 45678,
        "page_count": 23
    },
    "quality": {
        "overall_score": 0.85,
        "clarity": 0.9,
        "completeness": 0.8
    }
}

导入网页内容

从 URL 导入网页内容到知识库。

请求：

POST /admin/knowledge/import-url/{kb_id}
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID（路径参数）
url	string	是	网页 URL
auto_chunk	bool	否	是否自动分块（默认 true）
chunk_size	int	否	分块大小（默认 1000）

请求示例：

{
    "url": "https://example.com/article",
    "auto_chunk": true,
    "chunk_size": 1000
}

响应示例：

{
    "success": true,
    "kb_id": "kb_abc123def456",
    "url": "https://example.com/article",
    "extracted": {
        "title": "文章标题",
        "char_count": 5678,
        "word_count": 1234,
        "chunks_added": 6
    },
    "quality": {
        "overall_score": 0.82,
        "content_density": 0.85,
        "readability": 0.8
    }
}

批量导入 URL

一次导入多个网页。

请求：

POST /admin/knowledge/import-urls/{kb_id}
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID（路径参数）
urls	array	是	URL 列表（最多 20 个）

请求示例：

{
    "urls": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ]
}

知识库列表

获取所有知识库列表。

请求：

GET /admin/knowledge/
Authorization: Bearer {api_key}

响应示例：

{
    "knowledge_bases": [
        {
            "id": "kb_abc123",
            "name": "法律知识库",
            "status": "ready",
            "chunk_count": 156,
            "created_at": "2026-01-24T10:00:00Z"
        }
    ],
    "total": 1
}

搜索知识库

在知识库中搜索相关内容。

请求：

POST /admin/knowledge/search
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID
query	string	是	搜索关键词
top_k	int	否	返回数量（默认 5）

请求示例：

{
    "kb_id": "kb_abc123",
    "query": "合同违约如何处理",
    "top_k": 5
}

响应示例：

{
    "results": [
        {
            "chunk_id": "chunk_001",
            "text": "合同违约的处理方式包括...",
            "score": 0.92,
            "metadata": {
                "page": 15,
                "source": "合同法.pdf"
            }
        }
    ],
    "query": "合同违约如何处理",
    "kb_id": "kb_abc123"
}

专家 API

发布专家

将知识库发布为 AI 专家。

请求：

POST /admin/knowledge/expert/publish
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID
name	string	是	专家名称
description	string	是	专家描述
keywords	array	是	关键词列表
domains	array	否	领域标签
priority	int	否	优先级（1-10，默认 6）
greeting	string	否	欢迎语

请求示例：

{
    "kb_id": "kb_abc123",
    "name": "法律顾问专家",
    "description": "专注于民事法律咨询，提供专业法律建议",
    "keywords": ["法律", "合同", "诉讼", "维权"],
    "domains": ["legal", "consulting"],
    "priority": 7,
    "greeting": "您好，我是法律顾问专家，有什么可以帮助您的？"
}

响应示例：

{
    "success": true,
    "message": "专家「法律顾问专家」发布成功！",
    "expert": {
        "id": "expert_xyz789",
        "name": "法律顾问专家",
        "keywords_count": 15,
        "kb_id": "kb_abc123"
    }
}

发布前验证

检查知识库是否满足发布条件。

请求：

POST /admin/knowledge/expert/validate
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID

响应示例：

{
    "valid": true,
    "errors": [],
    "warnings": ["内容较少，可能影响回答质量"],
    "suggestions": ["建议上传更多相关文档"],
    "stats": {
        "kb_id": "kb_abc123",
        "status": "ready",
        "chunk_count": 50
    },
    "can_publish": true
}

一键优化专家信息

AI 自动优化专家配置。

请求：

POST /admin/knowledge/expert/auto-optimize?kb_id={kb_id}
Authorization: Bearer {api_key}

响应示例：

{
    "success": true,
    "optimized": {
        "name": "法律顾问大师",
        "description": "精通民法、合同法，提供专业法律咨询服务",
        "keywords": ["法律咨询", "合同纠纷", "民事诉讼", ...],
        "domains": ["legal"]
    }
}

专家列表

获取所有已发布的专家。

请求：

GET /admin/knowledge/expert/list
Authorization: Bearer {api_key}

响应示例：

{
    "experts": [
        {
            "id": "expert_xyz789",
            "name": "法律顾问专家",
            "description": "...",
            "kb_id": "kb_abc123",
            "keywords": ["法律", "合同"],
            "created_at": "2026-01-24T10:00:00Z"
        }
    ],
    "total": 1
}

专家状态

获取专家的运行状态。

请求：

GET /admin/knowledge/expert/{expert_id}/status
Authorization: Bearer {api_key}

响应示例：

{
    "expert_id": "expert_xyz789",
    "name": "法律顾问专家",
    "status": {
        "published": true,
        "loaded_in_router": true,
        "kb_available": true
    },
    "config": {
        "keywords_count": 15,
        "domains": ["legal"],
        "priority": 7
    }
}

对话 API

MCP 对话接口

主要的对话入口，支持专家匹配和知识库检索。

请求：

POST /mcp/analyze
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
text	string	是	用户输入
device_id	string	否	设备 ID
session_id	string	否	会话 ID
context	object	否	上下文信息

请求示例：

{
    "text": "合同违约怎么处理？",
    "device_id": "user_device_001",
    "session_id": "session_abc123"
}

响应示例：

{
    "response": "根据合同法规定，合同违约的处理方式主要有以下几种...",
    "expert": {
        "id": "expert_xyz789",
        "name": "法律顾问专家"
    },
    "sources": [
        {
            "text": "相关法条...",
            "score": 0.92
        }
    ],
    "session_id": "session_abc123"
}

WebSocket 实时对话

用于实时聊天的 WebSocket 连接。

连接：

wss://mbe.hi-maker.com/ws/chat?device_id={device_id}

发送消息：

{
    "type": "message",
    "text": "你好",
    "session_id": "session_abc123"
}

接收消息：

{
    "type": "response",
    "text": "您好！有什么可以帮助您的？",
    "expert": "法律顾问专家",
    "timestamp": "2026-01-24T10:00:00Z"
}

对话历史

获取用户的对话历史记录。

请求：

GET /api/v1/history/{device_id}?limit=20&offset=0
Authorization: Bearer {api_key}

响应示例：

{
    "history": [
        {
            "id": "msg_001",
            "role": "user",
            "content": "合同违约怎么处理？",
            "timestamp": "2026-01-24T10:00:00Z"
        },
        {
            "id": "msg_002",
            "role": "assistant",
            "content": "根据合同法规定...",
            "expert": "法律顾问专家",
            "timestamp": "2026-01-24T10:00:01Z"
        }
    ],
    "total": 100,
    "has_more": true
}

评估 API

评估 API 用于检查知识库和专家的质量。

知识库评估

评估知识库的权威性和内容质量。

请求：

POST /api/evaluation/knowledge-base
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID
include_authority	bool	否	包含权威性评估（默认 true）
include_quality	bool	否	包含质量评估（默认 true）

请求示例：

{
    "kb_id": "kb_abc123",
    "include_authority": true,
    "include_quality": true
}

响应示例：

{
    "evaluation_id": "eval_kb_abc123_1234567890",
    "evaluation_type": "knowledge_base",
    "target_id": "kb_abc123",
    "evaluated_at": "2026-01-24T10:00:00Z",
    "duration_seconds": 5.23,
    "overall_score": 78.5,
    "quality_level": "good",
    "passed": true,
    "dimensions": [
        {
            "name": "权威性",
            "score": 72,
            "max_score": 100,
            "description": "文档来源权威程度"
        },
        {
            "name": "内容质量",
            "score": 85,
            "max_score": 100,
            "description": "知识库内容的质量"
        }
    ],
    "strengths": ["内容量充足", "分块大小合理"],
    "weaknesses": ["未识别到权威出版社"],
    "recommendations": ["建议上传更多高质量文档"]
}

专家评估

测试专家的回答质量。

请求：

POST /api/evaluation/expert
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID
expert_id	string	否	专家 ID
num_tests	int	否	测试问题数量（5-100，默认 20）

请求示例：

{
    "kb_id": "kb_abc123",
    "num_tests": 20
}

响应示例：

{
    "evaluation_id": "eval_expert_abc123_1234567890",
    "evaluation_type": "expert",
    "overall_score": 75.2,
    "quality_level": "good",
    "passed": true,
    "dimensions": [
        {"name": "相关性", "score": 78, "max_score": 100},
        {"name": "完整性", "score": 72, "max_score": 100},
        {"name": "准确性", "score": 80, "max_score": 100},
        {"name": "响应速度", "score": 71, "max_score": 100}
    ],
    "raw_data": {
        "quality_report": {
            "total_tests": 20,
            "passed_tests": 16,
            "pass_rate": 80.0,
            "avg_response_time_ms": 1523
        }
    }
}

LLM Judge 评估

使用大语言模型作为评判者进行评估。

请求：

POST /api/evaluation/llm-judge
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID
test_dialogues	array	是	测试对话列表

请求示例：

{
    "kb_id": "kb_abc123",
    "test_dialogues": [
        {"question": "什么是合同违约？", "context": "法律咨询"},
        {"question": "违约金如何计算？", "context": "合同纠纷"}
    ]
}

响应示例：

{
    "evaluation_id": "eval_judge_abc123_1234567890",
    "evaluation_type": "llm_judge",
    "overall_score": 82.5,
    "quality_level": "excellent",
    "dimensions": [
        {"name": "准确性", "score": 80, "max_score": 100},
        {"name": "相关性", "score": 90, "max_score": 100},
        {"name": "同理心", "score": 80, "max_score": 100},
        {"name": "可行性", "score": 75, "max_score": 100},
        {"name": "完整性", "score": 85, "max_score": 100},
        {"name": "安全性", "score": 85, "max_score": 100}
    ]
}

评估汇总

一次性获取知识库的完整评估。

请求：

GET /api/evaluation/summary/{kb_id}
Authorization: Bearer {api_key}

响应示例：

{
    "kb_id": "kb_abc123",
    "evaluated_at": "2026-01-24T10:00:00Z",
    "knowledge_base": {
        "score": 78.5,
        "level": "good"
    },
    "expert_quality": {
        "score": 75.2,
        "level": "good"
    },
    "overall_score": 76.85,
    "recommendations": ["建议上传更多专业文档"]
}

市场 API

发布模型

将专家发布到市场。

请求：

POST /api/market/developer/models
Content-Type: application/json
Authorization: Bearer {api_key}

参数：

参数	类型	必填	说明
kb_id	string	是	知识库 ID
name	string	是	模型名称
description	string	是	模型描述
category	string	是	分类
price_per_1k_tokens	float	是	每千 Token 价格
tags	array	否	标签

请求示例：

{
    "kb_id": "kb_abc123",
    "name": "法律顾问 Pro",
    "description": "专业法律咨询服务",
    "category": "legal",
    "price_per_1k_tokens": 0.01,
    "tags": ["法律", "咨询"]
}

搜索市场

搜索市场中的模型。

请求：

GET /api/market/search?q=法律&category=legal&limit=10
Authorization: Bearer {api_key}

响应示例：

{
    "models": [
        {
            "model_id": "model_abc123",
            "name": "法律顾问 Pro",
            "description": "...",
            "price_per_1k_tokens": 0.01,
            "total_calls": 10000,
            "quality_score": 4.5
        }
    ],
    "total": 15
}

用户余额

查询用户余额。

请求：

GET /api/market/user/{user_id}/balance
Authorization: Bearer {api_key}

响应示例：

{
    "balance": 100.50,
    "free_tokens_daily": 1000,
    "free_tokens_used_today": 250,
    "total_spent": 50.00
}

用户 API

用户注册

请求：

POST /api/v1/users/register
Content-Type: application/json

参数：

参数	类型	必填	说明
email	string	是	邮箱
password	string	是	密码
name	string	否	用户名

用户登录

请求：

POST /api/v1/users/login
Content-Type: application/json

参数：

参数	类型	必填	说明
email	string	是	邮箱
password	string	是	密码

响应示例：

{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
        "id": "user_abc123",
        "email": "user@example.com",
        "role": "user"
    }
}

错误处理

HTTP 状态码

状态码	说明
200	成功
400	请求参数错误
401	未认证或认证失败
403	无权限访问
404	资源不存在
429	请求过于频繁
500	服务器内部错误

错误响应格式

{
    "detail": "错误详情",
    "code": "ERROR_CODE"
}

常见错误码

错误码	说明
INVALID_API_KEY	API Key 无效
QUOTA_EXCEEDED	配额已用尽
RATE_LIMITED	请求频率超限
KB_NOT_FOUND	知识库不存在
EXPERT_NOT_FOUND	专家不存在
INVALID_FILE_TYPE	文件类型不支持
FILE_TOO_LARGE	文件过大

限流规则

等级	QPS	日调用	月 Token
Trial	5	100	10万
Standard	20	1000	100万
Professional	100	10000	1000万
Enterprise	500	无限	协议定

文档版本: v1.0 更新时间: 2026-01-24

MBE API 参考文档

目录

概述

基础信息

请求格式

响应格式

认证方式

1. API Key 认证（推荐）

2. Device ID 认证

3. JWT Token 认证

知识库 API

创建知识库

上传文档

导入网页内容

批量导入 URL

知识库列表

搜索知识库

专家 API

发布专家

发布前验证

一键优化专家信息

专家列表

专家状态

对话 API

MCP 对话接口

WebSocket 实时对话

对话历史

评估 API

知识库评估

专家评估

LLM Judge 评估

评估汇总

市场 API

发布模型

搜索市场

用户余额

用户 API

用户注册

用户登录

错误处理

HTTP 状态码

错误响应格式

常见错误码

限流规则