MBE (Mises Behavior Engine) 使用手册

版本: 2.6
更新日期: 2026-01-27

📋 更新记录

目录

1. 系统概述
2. 用户角色系统 🆕 v2.2
3. 管理员指南
4. 开发者指南 🆕 v2.2
5. 用户指南
6. 专家市场与交易 🆕 v2.3
7. 智能专家推荐 🆕 v2.6
8. 多终端接入 🆕 v2.5
9. 在线学习 🆕 v2.5
10. 知识库设计向导 🆕 v2.4
11. 专家系统
12. 小智集成
13. API参考
14. 最佳实践
15. 模型训练

1. 系统概述

1.1 什么是MBE

MBE（Mises Behavior Engine，米塞斯行为引擎）是一个智能专家系统平台，支持：

• 📚 知识库管理：上传PDF/TXT/MD文档创建知识库
• 🧠 动态专家：基于知识库创建AI专家
• 🔗 MCP协议：与小智等智能设备无缝集成
• 👥 多用户支持：用户隔离的专家和Token管理

1.2 核心概念

1.3 系统架构

用户问题 → 小智终端 → MCP协议 → MBE → 专家路由 → 动态专家 → 知识库检索 → LLM生成 → 回答

2. 用户角色系统 🆕 v2.2

2.1 角色体系

MBE 采用三层角色体系，支持不同类型用户的差异化需求：

┌─────────────────────────────────────────────────────────────┐
│                    MBE 用户角色体系                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  【管理员体系】                                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │ super_admin │ │   admin     │ │  operator   │           │
│  │  超级管理员  │ │   管理员    │ │   运营员    │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
│                                                             │
│  【开发者体系】                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  developer (开发者)                                  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  【消费者体系】                                              │
│  ┌─────────────┐ ┌─────────────────────────────────────┐   │
│  │ enterprise  │ │            user                     │   │
│  │  企业用户   │ │          普通用户                    │   │
│  └─────────────┘ └─────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2.2 角色权限对比

2.3 访问入口

2.4 测试账号

系统预置了 21 个测试账号，密码统一为 Test@123：

管理员体系：

• admin@test.local (super_admin)
• manager@test.local (admin)
• operator@test.local (operator)

开发者体系：

• dev1@test.local ~ dev3@test.local (developer)

企业用户：

• enterprise1@test.local ~ enterprise3@test.local (enterprise)

普通用户：

• user1@test.local ~ user10@test.local (user)

3. 管理员指南

2.1 访问管理后台

URL: https://your-domain.com/api/knowledge/admin/ui

登录方式：

1. 首次访问需输入管理员密码
2. 密码在环境变量 MBE_ADMIN_PASSWORD 中配置
3. 登录后Cookie有效期24小时

2.2 知识库管理

创建知识库

1. 点击 "创建知识库" 按钮
2. 填写知识库名称和描述
3. 点击确认创建

上传文档

单文件上传：

1. 选择目标知识库
2. 点击 "上传文件" 或拖拽文件到上传区
3. 支持格式：PDF、TXT、MD
4. 文件大小限制：单文件 50MB

批量上传 🆕：

1. 点击 "选择文件夹" 或拖拽整个文件夹
2. 一次可上传多个文件
3. 后台异步处理，不阻塞操作

断点续传 🆕（>100MB文件）：

1. 大文件自动分块上传（5MB/块）
2. 上传中断后可恢复
3. 实时显示上传进度

上传流程：

上传文件 → 文本提取 → 权威性评估 🆕 → 智能分块 → TITANS向量嵌入 → 存储索引

文档处理详情

系统会自动：

• 提取PDF文本（保留页码信息）
• 权威性评估（A/B/C/D级）🆕
• 智能分块（按段落/章节）
• 生成向量嵌入（TITANS增强）
• 构建检索索引

PDF权威性评估 🆕

上传PDF时，系统自动评估内容可信度：

评估维度：

权威性等级：

识别的权威来源：

• 国际学术出版社：Springer、Wiley、Cambridge、Oxford、MIT Press
• 中文权威出版社：商务印书馆、中华书局、三联书店、北大/清华出版社
• 技术出版社：O'Reilly、机械工业、人民邮电
• 知名专家：系统内置专家名录

2.3 专家管理

发布专家

1. 在知识库详情页点击 "发布为专家"
2. 填写专家信息：

3. 点击 "发布"

专家匹配原理

用户问题匹配专家的算法：

1. 关键词匹配：问题中包含专家关键词
2. 语义相似度：问题与专家描述的向量相似度
3. 领域权重：同领域专家优先

2.4 统一Token管理

MBE v1.1+ 使用统一的Token管理服务，集中管理所有类型的Token。

Token类型

添加Token

1. 进入 "Token管理" 标签
2. 点击 "添加Token"
3. 输入：
   • Token ID（唯一标识）
   • 名称（显示用）
   • Token类型
   • Token值（会被加密存储）
   • 过期天数（可选）

Token安全特性

• 加密存储：所有Token使用Fernet加密存储
• 审计日志：记录所有Token操作
• 过期管理：支持设置过期时间和自动提醒
• 轮换支持：支持无缝Token轮换

小智Token获取方式

1. 登录 小智控制台
2. 进入设备管理
3. 选择设备 → MCP配置
4. 复制显示的MCP端点URL

2.5 系统监控

审计日志

位置：knowledge_bases/audit_logs/qa_log_YYYY-MM-DD.jsonl

记录内容：

{
  "timestamp": "2026-01-15T10:30:00Z",
  "expert_id": "xxx",
  "question": "用户问题",
  "chunks_retrieved": 5,
  "relevance_scores": [0.85, 0.72, ...],
  "answer_length": 500,
  "confidence": "high",
  "response_time_ms": 1200
}

查看用户统计

# 查看注册用户数
docker exec mbe-postgres psql -U mbe -d mbe -c "SELECT COUNT(*) FROM users;"

# 查看活跃用户
docker exec mbe-postgres psql -U mbe -d mbe -c "SELECT email, created_at FROM users ORDER BY created_at DESC LIMIT 10;"

4. 开发者指南 🆕 v2.2

4.1 开发者门户访问

URL: https://your-domain.com/developer/

功能概览：

• 📚 创建和管理知识库
• 📄 上传文档到知识库
• 🤖 发布 AI 专家
• 💰 查看收益和调用统计
• 🔑 管理 API Key

4.2 开发者工作流程

注册账号 → 申请开发者 → 创建知识库 → 上传文档 → 发布专家 → 获取收益

4.3 创建知识库

1. 登录开发者门户
2. 点击 "创建知识库"
3. 填写：
   • 知识库名称
   • 描述（用于匹配用户问题）
   • 语言（自动检测/中文/英文）

4.4 上传文档

支持格式：PDF、TXT、MD

上传方式：

• 单文件上传：拖拽或点击选择
• 批量上传：选择文件夹

处理流程：

上传 → 文本提取 → 权威性评估 → 智能分块 → 向量嵌入 → 存储

4.5 发布专家

知识库准备好后，可发布为 AI 专家：

1. 在知识库详情页点击 "发布为专家"
2. 系统自动生成：
   • 专家名称
   • 专家描述
   • 关键词（可手动补充）
3. 确认发布

4.6 收益说明

开发者可通过以下方式获得收益：

4.7 API 接入

开发者可获取 API Key 用于程序化访问：

import requests

API_KEY = "your_api_key"
response = requests.post(
    "https://mbe.hi-maker.com/api/expert/ask",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "expert_id": "your_expert_id",
        "question": "用户问题"
    }
)
print(response.json())

5. 用户指南

3.1 访问用户中心

URL: https://your-domain.com/api/portal/ui

3.2 用户注册

1. 访问用户中心页面
2. 切换到 "注册" 标签
3. 填写：
   • 邮箱（必填）
   • 密码（必填）
   • 昵称（可选）
4. 点击 "注册"

3.3 用户登录

邮箱登录：

1. 输入邮箱和密码
2. 点击 "登录"

设备登录（小智用户）：

1. 输入设备ID
2. 系统自动关联或创建用户

3.4 我的Token

登录后可以：

• 查看已添加的Token列表
• 添加新Token关联设备
• 测试Token连接状态

3.5 我的专家（高级用户）

Premium用户可以：

• 上传自己的PDF创建私有知识库
• 发布私有专家（仅自己可用）
• 管理专家关键词和描述

文件限制

6. 专家市场与交易 🆕 v2.3

6.1 访问专家市场

URL: https://your-domain.com/ui/market

专家市场是用户发现和使用AI专家的入口。

6.2 浏览专家

市场首页展示：

• 精选专家 - 平台推荐的高质量专家
• 热门专家 - 调用次数最多的专家

6.3 搜索与筛选

搜索方式：

1. 关键词搜索：在搜索框输入关键词，回车或点击搜索
2. 分类筛选：点击分类按钮（法律、医疗、财务、技术、教育、生活）

专家卡片信息：

• 专家名称和描述
• 评分（⭐）和调用次数
• 标签（领域关键词）
• 价格（每千Token费用）

6.4 使用专家

1. 在专家卡片点击 "立即使用"
2. 如未登录，系统提示前往登录
3. 登录后跳转到对话页面 /ui/chat?expert={id}

6.5 账单管理

URL: https://your-domain.com/ui/billing

账单页面功能：

6.6 充值与支付

充值流程：

点击充值 → 选择金额 → 选择支付方式 → 扫码支付 → 充值成功

支持金额：

• 预设金额：¥10、¥50、¥100、¥200、¥500、¥1000
• 自定义金额：输入任意金额

支付方式：

• 💚 微信支付
• 💙 支付宝

支付页面：

• 显示支付金额和二维码
• 5分钟倒计时
• 支付成功后自动跳转账单页面

6.7 订阅套餐

URL: https://your-domain.com/user/subscription

套餐类型：

Token充值（按需付费）：

7. 智能专家推荐 🆕 v2.6

7.1 推荐系统简介

MBE v1.9 引入了类抖音的智能专家推荐系统，为用户提供个性化的专家推荐。

核心特点：

• 🎯 个性化推荐：基于用户历史和偏好
• 📊 信任度评分：专家质量透明可见
• 🔄 探索与利用：既推荐熟悉专家，也发现新专家
• 💬 推荐解释：了解为什么推荐这个专家

7.2 专家信任度

每个专家都有一个 0-100 的信任度评分，基于以下维度：

信任等级：

7.3 个性化推荐

系统会根据以下因素为您推荐专家：

1. 意图匹配：您的问题与专家领域的匹配度
2. 历史偏好：您之前使用过的专家类型
3. 相似用户：与您相似的用户喜欢的专家
4. 新专家发现：偶尔推荐新上线的优质专家

7.4 推荐 API

获取个性化推荐：

GET /api/market/recommendations/for-user/{user_id}

基于问题推荐：

GET /api/market/recommendations/for-question?q=您的问题

查看专家信任度：

GET /api/trust/score/{expert_id}

信任度排行榜：

GET /api/trust/leaderboard

7.5 推荐解释

每个推荐都会附带解释，说明推荐理由：

{
  "expert_id": "民事律师",
  "trust_score": 92,
  "recommendation_reasons": [
    "与您的问题高度相关 (法律咨询)",
    "该专家信任度评分 92 分，属于优秀级别",
    "相似用户对该专家满意度达 95%"
  ]
}

8. 多终端接入 🆕 v2.5

8.1 智能手表 API

URL: /api/watch/

支持 WearOS/WatchOS 设备接入，针对小屏幕优化。

示例请求：

{
  "text": "帮我设定明天早上7点的闹钟",
  "device_type": "watch"
}

8.2 车载终端 API

URL: /api/vehicle/

支持 Android Auto/CarPlay 系统集成。

8.3 Home Assistant API

URL: /api/ha/

支持 Home Assistant 语音助手和自动化调用。

配置示例（configuration.yaml）：

rest_command:
  mbe_ask:
    url: "http://mbe-server:8000/api/ha/ask"
    method: POST
    headers:
      Content-Type: application/json
    payload: '{"question": "{{ question }}"}'

8.4 智能家电 API

URL: /api/appliance/

支持 10+ 种智能家电类型：

9. 在线学习 🆕 v2.5

9.1 反馈 API

URL: /api/feedback/

系统通过用户反馈持续优化专家匹配。

8.2 反馈类型

9.3 学习效果

• 专家匹配准确率持续提升
• 新关键词自动添加到专家配置
• 低质量匹配自动降权

10. 知识库设计向导 🆕 v2.4

10.1 访问向导

URL: /admin/knowledge/wizard/ui

需要开发者登录：向导需要开发者身份认证。

10.2 向导功能

10.3 开发者认证流程

访问向导 → 未登录跳转登录 → 登录成功 → 返回向导
                                  ↓
                    创建的知识库归属于该开发者

10.4 向导使用步骤

1. 选择领域模板 或 AI智能设计
2. 查看推荐的文档清单
3. 上传已有文件进行缺口分析
4. 点击"创建知识库"
5. 跳转到上传页面，上传剩余文档

11. 专家系统

11.1 专家类型

4.2 专家问答流程

1. 用户提问
   ↓
2. 专家路由（关键词+语义匹配）
   ↓
3. 选择最佳专家
   ↓
4. 知识库检索（RAG）
   ↓
5. 构建提示词（问题+上下文+来源）
   ↓
6. LLM生成回答
   ↓
7. 添加置信度和来源引用
   ↓
8. 返回用户

4.3 回答质量指标

置信度等级

来源引用

回答会包含：

• 来源文档名称
• 具体页码
• 相关度评分

示例：

根据《咖啡风味化学》第23页的内容，咖啡因含量与烘焙程度...
[来源: coffee_chemistry.pdf, 页码: 23, 相关度: 85%]

4.4 专家关键词优化

为提高匹配准确性：

好的关键词示例：

咖啡风味专家: 咖啡,风味,烘焙,萃取,酸度,苦味,香气,咖啡豆,手冲,意式

避免的问题：

• ❌ 关键词太少（<10个）
• ❌ 关键词太通用（如"问题","方法"）
• ❌ 与其他专家重叠严重

12. 小智集成

12.1 配置流程

1. 在小智控制台创建设备
   ↓
2. 获取MCP Token
   ↓
3. 在MBE添加Token
   ↓
4. 测试连接
   ↓
5. 配置小智System Prompt

12.2 小智System Prompt配置

推荐配置：

你是一个智能助手，可以调用专家系统来回答专业问题。

可用工具：
- ask_expert: 咨询专家，请直接显示专家的回答
- get_expert_list: 获取可用专家列表

使用规则：
1. 收到专业问题时，先调用ask_expert
2. 将专家的回答完整展示给用户
3. 如果专家系统不可用，使用自己的知识回答
4. 不要说"正在连接专家"，直接展示结果

5.3 MCP工具说明

ask_expert

咨询专家获取专业回答。

参数：

返回：

{
  "answer": "专家回答内容...",
  "expert_name": "咖啡风味专家",
  "confidence": "high",
  "sources": ["coffee.pdf:p23"]
}

get_expert_list

获取可用专家列表。

返回：

{
  "experts": [
    {
      "name": "咖啡风味专家",
      "description": "精通咖啡化学和风味",
      "domains": ["food", "beverage"]
    }
  ]
}

12.4 连接状态检查

在小智控制台查看：

• ✅ 绿色：已连接
• 🔴 红色：未连接

未连接排查：

1. 检查Token是否正确
2. 检查MBE服务是否运行
3. 查看xiaozhi-bridge日志

13. API参考

13.1 公开API

健康检查

GET /health

响应：

{"status": "healthy", "timestamp": "2026-01-15T12:00:00Z"}

用户注册

POST /api/portal/register
Content-Type: application/x-www-form-urlencoded

email=user@example.com&password=secret&nickname=用户名

用户登录

POST /api/portal/login
Content-Type: application/x-www-form-urlencoded

email=user@example.com&password=secret

6.2 MCP API

MCP工具调用

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "ask_expert",
    "arguments": {
      "question": "咖啡的主要化学成分是什么？"
    }
  },
  "id": 1
}

13.3 Token管理API

需要管理员密码认证。

获取Token统计

GET /api/tokens/stats
Cookie: mbe_admin_auth=xxx

响应：

{
  "stats": {
    "total": 5,
    "by_type": {"xiaozhi_mcp": 3, "llm_api": 1, "cloudflare": 1},
    "by_status": {"active": 4, "expired": 1},
    "expiring_soon": 1
  },
  "expiring_soon": [
    {"id": "xiaozhi_xxx", "name": "测试设备", "days_left": 5}
  ]
}

存储Token

POST /api/tokens/store
Cookie: mbe_admin_auth=xxx
Content-Type: application/json

{
  "token_id": "xiaozhi_device1",
  "name": "我的小智设备",
  "token_type": "xiaozhi_mcp",
  "value": "wss://api.xiaozhi.me/mcp/?token=xxx",
  "expires_in_days": 365
}

轮换Token

POST /api/tokens/{token_id}/rotate
Cookie: mbe_admin_auth=xxx
Content-Type: application/json

{
  "new_value": "new-token-value"
}

撤销Token

POST /api/tokens/{token_id}/revoke
Cookie: mbe_admin_auth=xxx

获取审计日志

GET /api/tokens/audit?token_id=xxx&limit=100
Cookie: mbe_admin_auth=xxx

13.4 知识库管理API

需要管理员密码认证。

创建知识库

POST /api/knowledge/create
Cookie: mbe_admin_auth=xxx

{
  "name": "咖啡知识库",
  "description": "关于咖啡的专业知识"
}

上传文件

POST /api/knowledge/{kb_id}/upload
Cookie: mbe_admin_auth=xxx
Content-Type: multipart/form-data

file: (binary)

发布专家

POST /api/knowledge/{kb_id}/publish
Cookie: mbe_admin_auth=xxx

{
  "expert_name": "咖啡专家",
  "description": "咖啡领域专家",
  "keywords": ["咖啡", "烘焙", "萃取"],
  "domains": ["food", "beverage"]
}

14. 最佳实践

14.1 知识库建设

文档选择

✅ 推荐：

• 权威教材、专业书籍
• 官方文档、技术手册
• 学术论文、研究报告

❌ 避免：

• 网络文章、博客
• 未经验证的内容
• 过时的资料

文档准备

1. PDF质量：确保文字可复制（非扫描件）
2. 结构清晰：有章节标题和目录
3. 内容聚焦：一个知识库专注一个领域

14.2 专家配置

关键词设置

原则：
1. 核心词汇：领域最重要的10个词
2. 同义词：常见的替代表达
3. 长尾词：具体的专业术语
4. 区分词：与其他专家区分的独特词

示例（咖啡专家）：
核心：咖啡,咖啡豆,烘焙,萃取,风味
同义词：咖啡因,黑咖啡,美式
长尾：手冲咖啡,意式浓缩,拿铁艺术
区分：（不用"饮料","健康"等通用词）

描述撰写

好的描述：
"精通咖啡化学成分、烘焙工艺和萃取技术，
能够解答关于咖啡风味特征、冲泡方法和品鉴技巧的专业问题。"

避免：
"一个关于咖啡的专家。"（太简单）
"无所不知的咖啡大师。"（太夸张）

14.3 小智使用

提问技巧

✅ 有效提问：

• "咖啡的主要化学成分有哪些？"
• "请咨询咖啡专家，如何选择咖啡豆？"

❌ 无效提问：

• "咖啡"（太短）
• "跟我聊聊咖啡吧"（太模糊）

问题定向

如果有多个相似专家，可以指定：

• "请问运动教练，如何制定健身计划？"
• "咨询医疗销售专家，产品定价策略"

14.4 性能优化

知识库大小

优化建议

1. 每个知识库保持5-10个文档
2. 删除冗余或过时文档
3. 使用具体关键词提高匹配速度

附录

A. 术语表

B. 文件格式支持

C. 常见问题

Q: 专家总是匹配错误怎么办？ A: 检查并优化专家关键词，确保独特性。

Q: 回答不够准确怎么办？ A: 上传更多高质量文档，或调整提问方式。

Q: 小智显示"专家系统无法连接"？ A: 检查MBE服务状态和Token配置。

Q: 如何提高回答的可信度？ A: 上传权威来源的PDF，系统会显示来源引用。

11. 模型训练

8.1 模型架构概述

MBE使用多层模型架构：

15.2 核心模型训练

当需要重新训练核心TITANS+MIRAS模型时：

# 使用GPU训练（推荐）
cd mises-behavior-engine
python scripts/retrain_titans_model.py

# 训练参数优化（防止OOM）
# - batch_size: 8
# - memory_dim: 256
# - num_memory_slots: 128
# - max_samples: 500
# - use_fp16: True（混合精度）

训练数据来源：

• training/datasets/*.json - 合成数据
• training/experts/*.json - 专家配置
• 用户交互历史（匿名化）

训练时间参考：

8.3 专家模型训练

训练特定领域的专家模型：

# 检查并训练专家模型
python scripts/check_and_train_experts.py

# 训练特定专家
python scripts/check_and_train_experts.py --expert civil_lawyer

已训练的专家模型：

• 中国民事律师专家 🏆 — 350,000+ 真实法院判决案例 (1985-2024)
• 中国证券律师专家
• 系统设计面试专家

15.4 模型质量评估

# 评估训练质量
python scripts/evaluate_training.py

# 功能测试
python scripts/test_titans_model.py

质量指标：

15.5 模型文件位置

15.6 何时需要重新训练

需要重新训练核心模型：

• 模型架构变更
• 新增核心功能
• 训练数据大幅更新

需要重新训练专家模型：

• 专家知识库更新
• 领域知识扩展
• 回答质量下降

不需要重新训练：

• 新增动态专家（自动处理）
• 上传新PDF到现有知识库
• 调整专家关键词

附录

A. 术语表

B. 文件格式支持

C. 常见问题

Q: 专家总是匹配错误怎么办？ A: 检查并优化专家关键词，确保独特性。

Q: 回答不够准确怎么办？ A: 上传更多高质量文档（A/B级权威性），或调整提问方式。

Q: 小智显示"专家系统无法连接"？ A: 检查MBE服务状态和Token配置。

Q: 如何提高回答的可信度？ A: 上传权威来源的PDF，系统会显示来源引用。

Q: 上传大文件失败怎么办？ 🆕 A: 使用断点续传功能，或将文件分割后批量上传。

Q: 权威性评估为D级怎么办？ 🆕 A: 建议更换来源更可靠的文档，或在使用时注明内容待验证。

文档版本: 2.6
最后更新: 2026-01-27
v2.6: 智能专家推荐系统、信任度评分、推荐解释
v2.5: 多终端接入（智能手表/车载/HA/智能家电）、在线学习
v2.4: 知识库设计向导、开发者认证、KB归属开发者
v2.3: 新增专家市场、账单系统、支付功能
v2.2: 用户角色系统、开发者门户
v2.0: 权威性评估、批量上传、TITANS模型训练说明