MBE 统一入门指南（Getting Started）

无论你是 API 集成开发者、系统部署运维，还是 产品经理/决策者，都从这里开始。

⏱ 预计阅读：5-10 分钟 ｜ 📋 首次 API 调用：< 2 分钟

📖 目录

• 1. MBE 是什么？
• 2. 快速体验（2 分钟 Hello World）
• 3. 核心概念
• 4. 集成路线
  • 4a. API 集成（推荐）
  • 4b. 本地部署
  • 4c. MCP 协议集成
• 5. 创建你的第一个专家
• 6. 评估你的专家
• 7. 安全与合规
• 8. 下一步
• 附录：术语表
• 附录：常见问题

1. MBE 是什么？

MBE（Mises Behavior Engine，米塞斯行为引擎） 是一个基于奥地利经济学派人类行为学理论的 AI 决策分析系统。

核心理念：每个回答都应该是可追溯、可验证、可信赖的。

用户提问 → 意图理解 → 专家匹配 → 知识检索 → 回答生成 → Self-Critique → 输出
                                                            ↑
                                                    安全护栏 × 15 道

主要能力

2. 快速体验（2 分钟 Hello World）

前置条件

• 一个 MBE 账号（注册入口）
• API Key（在开发者控制台生成）

2.1 用 cURL 调用

curl -X POST https://mbe.hi-maker.com/api/expert/ask \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "什么是合同违约的法律后果？"}'

2.2 用 Python 调用

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={"query": "什么是合同违约的法律后果？"}
)

data = response.json()
print(f"专家: {data['expert']}")
print(f"回答: {data['answer']}")
print(f"来源: {data['sources']}")

2.3 用 JavaScript/Node.js 调用

const response = await fetch("https://mbe.hi-maker.com/api/expert/ask", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "什么是合同违约的法律后果？" }),
});

const data = await response.json();
console.log(`专家: ${data.expert}`);
console.log(`回答: ${data.answer}`);

响应结构

{
  "success": true,
  "expert": "民事法律专家",
  "answer": "合同违约的法律后果主要包括...",
  "sources": [
    {"name": "民法典第577条", "confidence": 0.95}
  ],
  "confidence": 0.92
}

3. 核心概念

3.1 专家（Expert）

MBE 中的"专家"是一个 知识库 + 系统提示 + 行为约束 的组合体。

┌─────────────────────────────────────┐
│            动态专家                    │
├─────────────────────────────────────┤
│  📚 知识库 — PDF/TXT/网页/问答对       │
│  🎯 系统提示 — 角色定义与行为边界       │
│  🔒 约束 — 可靠性门禁 + Self-Critique  │
│  📊 评估 — 质量分数 + 净分数 + 信任度   │
└─────────────────────────────────────┘

3.2 Self-Critique（自我批评）

每次回答会经过 15 个验证模块 的检查：

3.3 可靠性门禁

专家上线前必须通过两级门禁：

一级门禁（必须 100% 达标）：
  ✅ 引用完整性  — 100% 回答有引用
  ✅ 零幻觉      — 100% 不允许幻觉
  ✅ 正确拒答    — 95%  在超出知识范围时拒答
  ✅ 来源忠实    — 95%  忠于知识库原文

二级门禁：
  ✅ 综合能力分 ≥ 85 分

3.4 净分数（Net Score）

净分数 = 正确率 − 错误率

三分类：
  correct    — 回答正确
  incorrect  — 回答错误（含幻觉）
  uncertain  — 主动拒绝/表达不确定  ← 鼓励这种行为

校准度 = uncertain / (uncertain + incorrect)
  → 衡量专家在不确定时是否选择拒答而非编造

4. 集成路线

4a. API 集成（推荐）

适合：快速对接、不想管理基础设施的团队。

你的应用  →  HTTPS  →  MBE API  →  动态专家  →  回答

步骤：

1. 注册账号，获取 API Key
2. 通过管理后台上传知识库、创建专家
3. 调用 /api/expert/ask 提问
4. （可选）调用 /api/evaluation/net-score 评估质量

详细 API 文档：API Reference

4b. 本地部署

适合：数据隐私要求高、需要定制化的团队。

前置条件：

快速启动：

# 1. 克隆仓库
git clone https://your-gitea-server/mises/mises-behavior-engine.git
cd mises-behavior-engine

# 2. 配置环境变量
cp .env.example .env.development.local
# 编辑 .env.development.local，填写 LLM API Key 等

# 3. 启动开发环境
.\start-dev.bat
# 或
docker compose -f docker-compose.dev.yml up -d

# 4. 验证
curl http://localhost:8001/api/health
# → {"status": "ok", "version": "..."}

详细部署文档：部署指南

4c. MCP 协议集成

适合：Cursor、Claude Desktop 等支持 MCP 的 AI 客户端。

{
  "mcpServers": {
    "mbe": {
      "url": "https://mbe.hi-maker.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

详细文档：MCP 集成指南

5. 创建你的第一个专家

5.1 通过 API 创建

import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://mbe.hi-maker.com"

# 步骤 1: 创建知识库
kb = requests.post(f"{BASE}/admin/knowledge/create", headers={
    "Authorization": f"Bearer {API_KEY}"
}, json={
    "name": "产品手册知识库",
    "description": "XX 产品的使用手册和常见问题"
}).json()
kb_id = kb["kb_id"]

# 步骤 2: 上传文档
with open("product_manual.pdf", "rb") as f:
    requests.post(f"{BASE}/admin/knowledge/upload/{kb_id}", headers={
        "Authorization": f"Bearer {API_KEY}"
    }, files={"file": f})

# 步骤 3: 等待索引完成（通常 30 秒 ~ 5 分钟）
import time
while True:
    status = requests.get(f"{BASE}/admin/knowledge/{kb_id}", headers={
        "Authorization": f"Bearer {API_KEY}"
    }).json()
    if status["status"] == "ready":
        break
    time.sleep(5)

# 步骤 4: 提问
answer = requests.post(f"{BASE}/api/expert/ask", headers={
    "Authorization": f"Bearer {API_KEY}"
}, json={
    "query": "这个产品支持哪些操作系统？",
    "kb_id": kb_id
}).json()

print(answer["answer"])

5.2 通过管理后台创建

1. 访问 管理后台
2. 点击 "创建知识库"
3. 上传 PDF/TXT/网页 URL
4. 等待索引完成
5. 在 "测试专家" 页面验证回答质量

6. 评估你的专家

6.1 净分数评估（推荐）

# 准备测试用例
test_cases = [
    {"question": "产品支持哪些系统？", "answer": "<专家的回答>", "reference": "Windows/Mac/Linux"},
    {"question": "价格是多少？", "answer": "<专家的回答>", "reference": "标准版 299/年"},
    {"question": "支持外星语吗？", "answer": "<专家的回答>", "reference": "不支持"},
]

result = requests.post(f"{BASE}/api/evaluation/net-score", headers={
    "Authorization": f"Bearer {API_KEY}"
}, json={
    "expert_id": "my_expert",
    "test_cases": test_cases
}).json()

print(f"净分数: {result['data']['net_score']}")
print(f"校准度: {result['data']['calibration_score']}")
print(f"解释:   {result['interpretation']['net_score_description']}")

6.2 可靠性门禁检查

curl -X POST https://mbe.hi-maker.com/api/evaluation/gate/{expert_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

6.3 评估指标参考

7. 安全与合规

MBE 内置四层安全防护体系：

L1 — 输入过滤（API 网关）
  ├── 正则 + 启发式 Prompt 注入检测
  ├── 知识库上传时间接注入扫描
  └── 敏感词 / 违禁词过滤

L2 — 上下文隔离（专家引擎）
  ├── 系统提示与用户输入标记分离
  ├── KB 检索结果附加 [REFERENCE_START/END] 标签
  └── 工具输出与指令通道分离

L3 — 行为监控（Self-Critique）
  ├── SC-12 有害内容检测
  ├── SC-13 隐私泄漏检测
  ├── SC-14 偏见检测
  ├── SC-15 情绪安全检测
  └── 输出异常检测（系统提示泄漏 / 角色脱离 / 可执行内容）

L4 — 持续测试
  ├── 定期红队测试
  ├── 自动化 Prompt 注入 Fuzzing
  └── 每月安全评估报告

8. 下一步

附录：术语表

附录：常见问题

Q: MBE 和 ChatGPT/Claude 有什么区别？

MBE 不是通用聊天机器人，而是 领域专家系统。每个专家只回答其知识库范围内的问题，超出范围会明确拒答。这确保了回答的可靠性和可追溯性。

Q: 支持哪些 LLM 后端？

MBE 支持多种 LLM 提供商，包括 OpenAI、Claude、通义千问、文心一言、DeepSeek 等。通过环境变量 LLM_PROVIDER 配置。

Q: 知识库支持哪些格式？

PDF、TXT、Markdown、DOCX、网页 URL。上传后自动进行分块、向量化和索引。

Q: 如何保证数据安全？

• 知识库数据存储在你自己的服务器上
• 支持私有化部署
• 所有用户输入经过 Prompt 注入检测
• 输出经过隐私泄漏检测
• 详见 隐私政策 和 数据安全策略

Q: 一个专家能处理多大的知识库？

单个知识库建议 < 100MB。对于大型知识库（如企业文档库），推荐拆分为多个主题知识库。

📬 遇到问题？请在 开发者反馈 提交，我们通常在 24 小时内回复。