安装

1555 字约 5 分钟

2026-03-23

1. 先决条件

Python 3.11+
一个 Anthropic 兼容的网关 URL + API key（示例使用 http://35.220.164.252:3888）
可选：MySQL / PostgreSQL 客户端库（只有当 db 指向这些后端时才需要）

提示

DataMind 不需要 claude CLI 或 claude-agent-sdk（SDK backend 可选）。默认循环通过官方 anthropic Python SDK 直接对接网关——某些环境里的 claude 是被厂商改过的二进制，会忽略 ANTHROPIC_API_KEY，我们彻底绕开了这个问题。

2. 安装

从 PyPI 安装（推荐）

pip install datamind

# 可选 extras
pip install 'datamind[mysql]'         # MySQL dialect
pip install 'datamind[postgres]'      # PostgreSQL dialect
pip install 'datamind[voyage]'        # Voyage embeddings
pip install 'datamind[huggingface]'   # 本地 BGE / e5 embedding
pip install 'datamind[dev]'           # pytest + build + twine

pip install datamind 会一并 ship 运行时代码、浏览器 UI（datamind/static/app.html）和默认 skill catalog（code-review、db-ops-sop），datamind chat 和 python -m uvicorn datamind.server:app 都不用 clone 仓库就能跑。

v1.0.0 稳定基线

native backend + 本地 profile 存储是 v1.0.0 的稳定 core。SDK/CCR、远程数据库适配器和自定义 provider 属于 integration 路径，发布前请在目标环境单独验证。公网部署还必须加认证、授权、TLS、限流和网络隔离，详见安全边界。

从源码安装（开发者）

git clone https://github.com/OpenDCAI/DataMind.git
cd DataMind
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'

仓库根的 static/ 和 .claude/skills/ 是开发权威源；server 跑在 checkout 时优先用仓库版本，跑在 pip 安装环境时 fallback 到包内捆绑版本。

3. 配置

cp .env.datamind.example .env.datamind
$EDITOR .env.datamind

最少配置：

DATAMIND__LLM__API_BASE=http://35.220.164.252:3888
DATAMIND__LLM__API_KEY=sk-your-key-here
DATAMIND__LLM__MODEL=claude-sonnet-4-6

就这么多。同一个 key 也给 embedding 用——如果没单独设 DATAMIND__EMBEDDING__*，embedding provider 会自动回退到 LLM 凭证。

MinerU 文档解析（可选）

DataMind 的 PDF 导入默认优先调用 MinerU Hosted API，失败后自动回退到 pypdf。不配置时仍可使用 pypdf；MinerU 不需要安装在本机。

DATAMIND_MINERU=auto
DATAMIND_MINERU_API_URL=https://mineru.net/api/v1/agent
DATAMIND_MINERU_API_TIMEOUT_S=180
DATAMIND_MINERU_LANGUAGE=ch
DATAMIND_MINERU_OCR=false

设置 DATAMIND_MINERU=off 可强制只使用 pypdf。MinerU Agent API 对文件大小、页数和请求频率有限制，复杂或大文件可配置自己的 MinerU API 服务。

4. 验证网关连通

python -m datamind.scripts.hello_sdk

预期输出：

[hello_sdk] gateway = http://35.220.164.252:3888/
[hello_sdk] model   = claude-sonnet-4-6
[hello_sdk] prompt  = 'Reply with just the single word: pong'
[hello_sdk] --- stream ---
pong
[hello_sdk] OK: gateway reachable, streaming works, model replied 'pong'.

这一步失败的话，后面都别往下做——先把 API key / base URL 修对。

5. 单独跑每个能力

每个能力都配了一个独立冒烟脚本，都用临时 profile（hello_<cap>_demo），不会碰你的真实数据。

python -m datamind.scripts.hello_kb       # Chroma + hybrid 检索器
python -m datamind.scripts.hello_db       # SQLite + NL2SQL + 安全闸
python -m datamind.scripts.hello_graph    # NetworkX 多跳遍历（不需要 LLM）
python -m datamind.scripts.hello_skills   # SKILL.md 语义检索
python -m datamind.scripts.hello_memory   # 短期 + 长期 + 事实抽取
python -m datamind.scripts.hello_agent    # 完整 Agent——4 个真实中文提问

6. 启动完整 Agent

# 交互式 REPL
python -m datamind chat

# 一次性提问
python -m datamind ask "如何做好代码审查？"

# 为当前 profile 构建 / 重建 KB 向量索引
python -m datamind ingest

# 打印配置 + 已注册的所有工具
python -m datamind info

7. HTTP 服务 + 浏览器 UI

python -m uvicorn datamind.server:app --host 127.0.0.1 --port 8000

在浏览器打开 http://127.0.0.1:8000 即可使用 Chat UI：流式回答、可折叠的工具调用卡片、侧边栏（配置 / 工具清单 / 图谱统计 / KB 文档 / 记忆查看器 / 一键重建索引）。

也可以直接用 API：

方法 + 路径	作用
`GET /`	浏览器 UI（服务 `static/app.html`）
`GET /api/health`	存活 + 配置快照
`GET /api/tools`	所有已注册工具的名字、描述、JSON schema
`POST /api/ask`	非流式
`POST /api/store`	调用 StoreAgent 写入数据并返回 receipts
`POST /api/chat`	真 SSE 流 — `text` / `tool_use` / `tool_result` / `done` 事件
`POST /api/upload`	保存上传文件并返回建议的 StoreAgent 提示（上传本身不会自动入库）
`POST /api/kb/reindex`	重建 KB
`GET /api/kb/documents`	当前 profile 下的文档清单
`GET /api/memory/{namespace}`	查看某 namespace 的记忆
`GET /api/graph/stats`	图谱节点 / 边统计

快速测：

curl -s http://127.0.0.1:8000/api/health | jq
curl -s -X POST http://127.0.0.1:8000/api/ask \
  -H 'Content-Type: application/json' \
  -d '{"message":"你好"}' | jq

流式：

curl -N -X POST http://127.0.0.1:8000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"告诉我 Status meeting 的时间"}'

7a. （可选）切到 `claude-agent-sdk` backend

DataMind 自带两套 agent loop 实现，通过 DATAMIND__AGENT__BACKEND 一个环境变量切换：

Backend	路径	适合场景
`native`（默认）	纯 Python，`anthropic` SDK 直连网关	部署最简、依赖最少
`sdk`	`claude-agent-sdk` → `claude` CLI → CCR → 你的网关	想白嫖 Hooks / Subagents / Compaction / Plan mode

23 个 DataMind 工具、SSE 事件协议、前端页面两套下完全一致——只有内部 loop 不同。

为什么需要 CCR

SDK 始终说 Anthropic 协议（/v1/messages）。如果你的网关只支持 OpenAI 格式（/v1/chat/completions），中间塞一层 claude-code-router（CCR）就能互转——一个很小的 Node 进程，单次请求开销 ~20ms。

启动 CCR

# 需要 node >= 18
export UPSTREAM_BASE=http://your-gateway.example.com/v1
export UPSTREAM_KEY=sk-...
export UPSTREAM_MODEL=claude-sonnet-4-6

bash scripts/start_ccr.sh
# → 监听 http://127.0.0.1:13456

另起一个终端留给它跑着。

切 DataMind 到 SDK backend

# .env.datamind 里或直接 export：
export DATAMIND__AGENT__BACKEND=sdk
export DATAMIND__AGENT__CCR_BASE_URL=http://127.0.0.1:13456

# 其他一切照旧：
python -m datamind chat
python -m uvicorn datamind.server:app --port 8000

server 启动日志里能看到 backend 选择：

INFO agent_loop_backend backend=sdk ccr=http://127.0.0.1:13456

随时切回 native（DATAMIND__AGENT__BACKEND=native 或直接不设）。

8. 跑单测

pytest
# 161 passed, 5 skipped — 不打网络

完整的 native / SDK 支持矩阵和稳定 API 合约记录了 v1.x 的兼容边界。

v0.1 仍可用

如果你要对照，旧 main.py / server.py / modules/ 原样保留。它仍然读旧的 .env key（LLM_API_BASE、LLM_API_KEY 等）。

可用网关与模型

任何 Anthropic 兼容的 /v1/messages 服务都能跑。在 http://35.220.164.252:3888 上验证过的模型：

模型	适用场景
`claude-opus-4-7`	复杂推理 / subagent
`claude-sonnet-4-6`	主 Agent（默认）
`claude-haiku-4-5-20251001`	Memory 事实抽取 / 廉价子任务

常见问题

现象	处理
`ValidationError: llm.api_key: Field required`	在环境变量或 `.env.datamind` 里设 `DATAMIND__LLM__API_KEY`
`401 Invalid token`	key / 网关不匹配，先用 `curl $BASE/v1/messages` 验证
`Unknown embedding provider 'openai'`	要在仓库根目录运行，保证能 `import datamind`
`no such table: employees`	NL2SQL 前没种子数据，先跑 `hello_agent.py` 或手动 INSERT
HTTP server 返回 `Agent not ready`	lifespan 还在热身，等几秒再查 `/api/health`