模型原生、协议优先、本地优先的多模型编排网关
中文 | English
OrchestrLM 是一个开源的 model-native multi-model orchestration gateway：它不重新发明 Agent 应用框架，而是用统一的 OpenAI-compatible API，把具备不同能力、成本和部署位置的本地/云端模型组合成一个可直接接入现有客户端的“虚拟模型”。
它优先面向 Apple Silicon 与 Ollama，同时保持标准 Python/FastAPI 架构，不把运行环境限制在 macOS。
LangChain 侧重用模型、工具、Prompt 与中间件构建 Agent 应用；AutoGen 侧重 Agents、Teams、消息传递和通用多智能体模式。OrchestrLM 不与它们争夺同一抽象层，而是聚焦更靠近模型接入层的五件事：
- 保留模型原生能力：推理、流式输出和
tool_calls尽量按上游模型能力与 OpenAI 协议传递，而不是把模型包进重型框架后重新定义一套工具语义。 - 按能力组合异构模型：让不同 Provider、参数规模和专业特长的模型承担路由、生成、审查或执行提议，并设置步数、并发、超时和失败上限。
- 对客户端保持一个模型入口：IDE、CLI 或 Web UI 只需连接
orchestrlm，不必理解后端有多少模型或采用了何种协作路径。 - 把执行权与模型建议分开：内部专家只使用工作区内受限的只读工具；有副作用的客户端工具由模型提出标准
tool_calls，交回客户端执行。 - 提供安全、可观测的编排协议：调度、专家状态、安全推理摘要、答案增量和工具请求使用独立事件，避免把内部状态混入普通回答。
因此，OrchestrLM 可以作为独立网关使用，也可以成为 LangChain、AutoGen 或任何 OpenAI-compatible 客户端的上游“虚拟模型”。
- 单模型与多模型分流：
auto、single、orchestrated三种响应模式。 - 动态专家路由：Manager 根据任务类型选择 GENERAL、ARCHITECT、CODER、REVIEWER、DEBUGGER、PM 或 EXECUTOR。
- 端到端流式输出：单模型路径可将上游 Token 增量转换为 OpenAI Chat Completions SSE。
- 结构化编排事件：调度、专家开始、专家完成、答案增量和工具调用使用独立事件。
- 安全推理展示：模型内部推理默认开启、对用户默认隐藏；仅在客户端请求且服务端允许时展示程序生成的阶段摘要，绝不透传原始 chain-of-thought。
- 本地与云端模型：支持 Ollama，以及 OpenAI-compatible 云端接口。
- 模型原生工具调用：工具定义传给具备原生 Tool Calling 能力的模型；服务端只闭环执行内置只读工具，客户端工具请求按 OpenAI
tool_calls返回。 - 工具安全边界：内部工具只读、限制在项目工作区；客户端提供的写入类工具由客户端执行。
- 安全默认值：默认只监听回环地址，配置接口脱敏，远程开放需显式设置 Token 和可信 CORS 来源。
- Web 控制台：实时查看任务调度、专家状态、答案流和遥测记录。
flowchart LR
Client[IDE / CLI / Web UI] --> Gateway[FastAPI gateway]
Gateway --> Mode{Response mode}
Mode -->|single| General[Direct model]
Mode -->|orchestrated| Manager[Manager router]
Manager --> Experts[Expert pool]
General --> Stream[OpenAI-compatible stream]
Experts --> Stream
Stream --> Client
编排模式中的典型事件：
dispatch -> expert_started -> reasoning_delta? -> answer_delta -> expert_completed -> final
其中 reasoning_delta 只能承载安全阶段摘要，不能承载模型原始隐藏推理。
- Python 3.10+
- Ollama（使用本地模型时）
- macOS、Linux 或 Windows；Apple Silicon 是主要优化场景
git clone https://github.com/alexjiang1/orchestrlm.git
cd orchestrlm
bash scripts/setup.sh也可以手动安装：
python3 -m venv venv
source venv/bin/activate
python -m pip install -e .
cp config/nexus_config.example.json nexus_config.json
cp .env.example .env
chmod 600 nexus_config.json .env当前 Python 导入包仍为 nexus，以保持 v0.2 兼容：
python -m nexus.server服务默认地址：
- Web UI：
http://127.0.0.1:8003 - OpenAI-compatible API：
http://127.0.0.1:8003/v1 - Health check：
http://127.0.0.1:8003/healthz
默认配置使用以下 Ollama 模型，可按设备能力修改：
ollama pull qwen3:8b
ollama pull qwen3:30b-a3b
ollama pull deepseek-r1:32b
ollama pull gemma3:27bcurl http://127.0.0.1:8003/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "orchestrlm",
"response_mode": "auto",
"messages": [{"role": "user", "content": "解释这个项目的架构"}]
}'curl -N http://127.0.0.1:8003/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "orchestrlm",
"stream": true,
"response_mode": "orchestrated",
"reasoning": {
"enabled": true,
"effort": "medium",
"visible": true
},
"messages": [{"role": "user", "content": "审查一个 FastAPI 服务的安全边界"}]
}'reasoning.visible=true 只是客户端请求；服务端还必须启用 reasoning_summary_allowed，才会返回安全摘要。
复制模板后编辑本地配置：
cp config/nexus_config.example.json nexus_config.json
cp .env.example .env以下文件包含本地密钥、提示词或运行数据，已被 .gitignore 排除，不应提交：
.env
nexus_config.json
*.jsonl
*.log
.workbuddy/
密钥优先使用环境变量注入。为兼容 v0.2，环境变量暂时保留 NEXUS_ 前缀：
export NEXUS_CLOUD_BASE_URL="https://api.example.com/v1"
export NEXUS_CLOUD_API_KEY="..."默认服务仅监听 127.0.0.1。如果需要对局域网或公网开放，至少设置：
export NEXUS_HOST="0.0.0.0"
export NEXUS_API_KEY="a-long-random-token"
export NEXUS_ADMIN_TOKEN="another-long-random-token"
export NEXUS_CORS_ORIGINS="https://your-trusted-client.example"不要在没有认证和网络边界保护的情况下直接暴露服务。
OrchestrLM 不试图用自己的 DSL 取代模型原生 Tool Calling。对于客户端提供的工具，模型负责根据名称、描述和 JSON Schema 生成调用意图；OrchestrLM 负责选择哪个模型获得哪些工具、规范化 Provider 差异、限制调用轮次，并决定工具在服务端执行还是委托给客户端。
系统的有效工具能力可以写成：
有效工具能力 = 模型的 Tool Calling 能力
× 当前授予的工具集合
× Provider 协议适配完整度
× 执行环境与权限
× 工具结果回注与多轮闭环
× 超时、审批、审计和安全策略
所以，模型决定“会不会正确调用”，编排层决定“能调用什么、在哪里执行、是否允许、失败后如何收敛”。两者不是竞争关系，也不能简单画等号。
当前边界：
- 内部专家可使用
read_file、list_directory、search_code，由 OrchestrLM 在工作区沙箱内执行并把结果回注给模型。 - EXECUTOR 可获得客户端传入的工具定义；模型生成的
tool_calls原样交回客户端执行，OrchestrLM 不在服务端执行未知或有副作用的工具。 max_tool_rounds限制内部工具循环，防止无界调用。- 当前
single/DIRECT路径尚未把客户端工具交给直答模型；tool_choice已进入请求模型但尚未完整下传；带工具时的 Provider Token 级流式仍需继续补齐。这些列入路线图，不在当前版本中夸大。
当前实现覆盖常用的 Chat Completions 子集：
messagesstreamtools/tool_calls（当前以编排模式的 EXECUTOR 委托和内部只读工具闭环为主）temperature、max_tokens、tool_choice可被请求模型接收，但尚未全部下传至上游 Provider- 自定义
response_mode - 自定义
reasoning - 自定义
nexus_event编排扩展
项目不宣称完整实现 OpenAI API 的全部参数与端点。
python -m pip install -e ".[dev]"
ruff check nexus tests scripts
mypy nexus
pytest --cov=nexus --cov-report=term-missing --cov-fail-under=50
python -m compileall -q nexus tests scripts
bash -n scripts/setup.shCI 在 macOS 和 Python 3.13 环境执行 lint、类型检查及测试覆盖率门禁。
orchestrlm/
├── config/ # 无密钥配置模板
├── docs/ # 架构文档
├── examples/ # 历史原型和调用示例
├── nexus/ # v0.2 兼容 Python 包
│ ├── client.py # Ollama / OpenAI-compatible 客户端
│ ├── config.py # 配置校验、脱敏与原子保存
│ ├── manager.py # 有界编排状态机
│ ├── router.py # 路由决策模型与解析
│ ├── server.py # FastAPI 网关
│ ├── tasks.py # 任务隔离与取消
│ └── tools.py # 沙箱内只读工具
├── scripts/ # 安装与数据导出脚本
├── tests/ # 自动化测试
└── web/index.html # Web 控制台
- OpenAI-compatible FastAPI 网关
- 单模型与多模型响应模式
- Token 级流式输出
- Ollama 与云端模型接入
- 安全推理摘要与结构化编排事件
- 配置脱敏、任务隔离和只读工具沙箱
- Provider 原生
tool_calls解析、内部只读工具闭环与客户端工具委托 - 让
single/DIRECT模式也可直接使用客户端工具 - 完整下传并验证
tool_choice、temperature、max_tokens等参数 - 实现带工具场景的 Provider Token /
tool_calls增量流式与跨 Provider 一致性测试 - 增加工具能力画像、按模型能力路由、策略审批、幂等键和细粒度审计
- 扩充 Provider 模拟测试与覆盖率
- 发布稳定的 Python API 与迁移后的包命名
- 增加可复现的多模型 Benchmark
- 完善 MLX Manager 微调流程
欢迎提交 Issue 和 Pull Request。开始前请阅读 CONTRIBUTING.md。
本项目基于 MIT License 开源。