exo 贡献指南：源码构建、Model Card TOML 规范与 API 适配器开发

exo 贡献指南：源码构建、Model Card TOML 规范与 API 适配器开发

【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exo

本文为 exo（"Run frontier AI locally"，跨 Mac/Apple Silicon 集群运行前沿大模型的开源项目）的贡献者技术指南。文章基于仓库的CONTRIBUTING.md编写，并结合当前源码补全了文档中未展开的细节：如何从零克隆并跑起源码版 exo（含 Rust 绑定与 Svelte 仪表盘构建）、TOML 格式的 Model Card 完整字段规范（含内置 123 张推理模型卡与 18 张图像模型卡实例）、以及 exo 多 API 格式适配器的内部架构与新增适配器的标准步骤。读完你可以独立完成源码环境搭建、为新模型提交模型卡、并为 exo 增加一个新的 OpenAI/Claude 风格 API 端点。

一、从源码运行 exo：前置依赖与构建流程

exo 是一个 Rust + Python + TypeScript（Svelte）混编项目，从源码构建需要三类工具链：Python 依赖管理工具 uv、Rust 工具链（用于编译rust/exo_rs的 Python 绑定，目前需要 nightly）、以及 Apple Silicon 硬件监控工具 macmon。

1.1 前置依赖安装

uv（Python 依赖管理）：

brew install uv

Rust 工具链（构建rust/exo_rs绑定需要 nightly）：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup toolchain install nightly

macmon（Apple Silicon 硬件监控，worker 侧用于采集硬件指标）：

cargo install --git https://github.com/vladkens/macmon \ --rev a1cd06b6cc0d5e61db24fd8832e74cd992097a7d \ macmon \ --force

注意这里必须使用仓库固定的 fork 修订版（--rev a1cd06b6...），而不是 Homebrew 的 macmon——仓库 python/utils/info_gatherer 中解析 macmon 输出的逻辑是针对该版本行为对齐的，用其他版本可能导致指标解析失败。

1.2 克隆与构建

git clone https://gitcode.com/GitHub_Trending/exo8/exo.git cd exo/dashboard npm install && npm run build && cd .. uv run exo

构建顺序背后的原因：uv run exo启动的服务会内嵌托管仪表盘页面，而仪表盘是 SvelteKit 应用（位于 dashboard/，源码在 dashboard/src/），必须先npm run build生成静态产物，主进程才能找到它。这一点可以从 Python 侧对仪表盘产物路径的依赖印证——src/exo/utils/dashboard_path.py 专门负责定位 dashboard 构建输出，且 src/exo/shared/constants.py 中支持通过EXO_DASHBOARD_DIR环境变量覆盖该路径。

另外从 pyproject.toml 可以看到两个适用于当前仓库的重要约束：

• requires-python = "==3.13.*"：Python 版本被严格锁在 3.13，uv 会自动准备对应解释器；
• [project.scripts]中定义了exo = "exo.main:main"，即uv run exo实际调用的是 src/exo/main.py 的main入口。

推理引擎侧的 MLX 相关依赖（mlx、mlx-lm、mflux、torch 等）定义在mlx可选依赖组中，并带有 darwin/linux 平台条件；Linux 上还细分了mlx-cpu、mlx-cuda12、mlx-cuda13三组互斥 extra（见pyproject.toml的[tool.uv.conflicts]），非 Apple 平台开发者安装时需按目标硬件选择对应 extra。

二、开发规范：一次 PR 一件事，注释解释"为什么"

CONTRIBUTING 对开发流程提出了三条硬性要求：

1. 开工前先拉取最新源码，保证基于最新代码工作；
2. 保持改动聚焦——一个 PR 只实现一个功能或修复一个 bug；
3. 即使看起来很小，也不要把不相关的改动混在一起。

代码风格方面，文档的要求与仓库的工具链配置一一对应：

• 尽量写纯函数；新增代码优先使用 Rust（除非有充分理由），项目把 Rust 用于网络层、进程管理等贴近系统的部分（见 rust/exo_rs/ 与 rust/networking/）；
• 充分利用三套类型系统：Rust 类型、Python type hints、TypeScript 类型。仓库对 Python 侧执行的是严格模式检查——pyproject.toml中[tool.basedpypyright]配置为typeCheckingMode = "strict"且failOnWarnings = true，reportAny、reportMissingParameterType等全部提升为 error，所以"补全类型标注"在这个仓库不是可选项；
• 注释解释"为什么"而不是"做什么"，尤其是非显而易见的决策；
• 提交前运行nix fmt自动格式化（仓库提供 flake.nix 与 justfile 组织开发命令）。

三、Model Card：TOML 模型卡的完整规范

这是 exo 贡献工作流中技术含量最高、也最值得深入的部分。exo 用 TOML 格式的Model Card描述每个模型的元数据与能力，是调度器做节点放置（placement）、下载器做分片规划、引擎做并行决策的单一事实来源。

3.1 模型卡的存放位置

源码中这三处路径分别落在 src/exo/shared/models/model_cards.py 的_BUILTIN_CARD_DIRS（内置两个目录）与 src/exo/shared/constants.py 的EXO_CUSTOM_MODEL_CARDS_DIR = EXO_DATA_HOME / "custom_model_cards"。加载逻辑是：card_cache.refresh()先扫两个内置目录再扫自定义目录，同一个model_id先加载者生效（缓存以model_id为键做去重）。

3.2 新增一张模型卡

按文档规范，新建一个 TOML 文件即可，完整示例（原样继承自 CONTRIBUTING）：

model_id = "mlx-community/Llama-3.2-1B-Instruct-4bit" n_layers = 16 hidden_size = 2048 supports_tensor = true tasks = ["TextGeneration"] family = "llama" quantization = "4bit" base_model = "Llama 3.2 1B" capabilities = ["text"] [storage_size] in_bytes = 729808896

必填字段：

可选字段：

• components：多组件模型专用（如图像模型有独立的 text encoder 与 transformer，见 3.4 节实例）；
• uses_cfg：是否使用 classifier-free guidance（图像模型）；
• trust_remote_code：是否允许从 HF Hub 执行远程代码，安全上默认应当保持关闭。

结合当前源码有两点值得补充：

1. 当前 schema 还要求backends字段。ModelCard中backends: list[Backend]没有默认值，内置卡都显式声明了支持的运行后端，例如 resources/inference_model_cards/mlx-community--GLM-4.5-Air-8bit.toml：

   model_id = "mlx-community/GLM-4.5-Air-8bit" n_layers = 46 hidden_size = 4096 num_key_value_heads = 8 supports_tensor = false tasks = ["TextGeneration"] family = "glm" quantization = "8bit" base_model = "GLM 4.5 Air" capabilities = ["text", "thinking", "thinking_toggle"] reasoning_dialect = "post_last_user" context_length = 131072 backends = ["MlxMetal", "MlxCuda", "MlxCpu"] [storage_size] in_bytes = 122406567936 # Source: https://docs.z.ai/api-reference/llm/chat-completion [sampling_defaults] temperature = 0.6 top_p = 0.95

   注意文件命名约定：目录内文件名用--替代model_id中的/（如mlx-community--GLM-4.5-Air-8bit.toml）。这张卡还演示了文档未展开的两个高级字段：reasoning_dialect（推理/思维链解析方言，用于决定如何剥离模型输出的 thinking 块）和[sampling_defaults]（该模型的官方推荐采样参数，支持thinking/non_thinking两套分组默认值，对应SamplingDefaults结构）。

2. num_key_value_heads也是可选字段，它对 KV Cache 内存估算直接影响多机放置决策，添加 MoE/多注意力头模型时建议显式给出。

3.3 卡片加载与缺失时的自动抓取

ModelCard的加载流程定义在 src/exo/shared/models/model_cards.py：

1. 先查内存缓存card_cache（以model_id为键）；
2. 缓存未命中则刷新全部目录后重查；
3. 仍缺失时走ModelCard.fetch_from_hf(model_id)：从 HF 下载config.json解析出n_layers、hidden_size、num_key_value_heads、max_position_embeddings等（ConfigData兼容num_hidden_layers、n_layer、num_decoder_layers等多种别名，并支持多模态配置下的text_config转发），再从model.safetensors.index.json的metadata.total_size得到存储大小（缺失时回退到 HF API 的 safetensors 总大小）；
4. 自动生成的卡片会打上is_custom=True并立即持久化到~/.exo/custom_model_cards/，下次启动无需再走网络。

其中两个细节值得关注：

• ConfigData.supports_tensor是一个按架构白名单判断的属性——当前源码中仅LlamaForCausalLM、DeepseekV3ForCausalLM、Qwen3MoeForCausalLM、Glm4MoeLiteForCausalLM、GptOssForCausalLM等少数架构被列为支持张量并行，其余自动判为false。贡献新模型卡时，supports_tensor的取值应与这份白名单的判断口径保持一致；
• 自动抓取生成的卡片会把backends设为全部后端，源码注释解释得很直白：不知道任意 HF 模型实际支持什么，"让放置层（placement gate）去把关"。

3.4 多组件模型卡：以 FLUX.1-Kontext 为例

图像模型往往由多个可独立加载的组件构成（text encoder、transformer、VAE）。CONTRIBUTING 提到components字段用于此类模型，仓库中的真实样例 resources/image_model_cards/exolabs--FLUX.1-Kontext-dev.toml 展示了完整写法：

model_id = "exolabs/FLUX.1-Kontext-dev" n_layers = 57 hidden_size = 1 supports_tensor = false tasks = ["ImageToImage"] family = "flux" capabilities = ["image_edit"] backends = ["MlxMetal"] [storage_size] in_bytes = 33327437952 [[components]] component_name = "text_encoder" component_path = "text_encoder/" n_layers = 12 can_shard = false [components.storage_size] in_bytes = 0 [[components]] component_name = "transformer" component_path = "transformer/" n_layers = 57 can_shard = true safetensors_index_filename = "diffusion_pytorch_model.safetensors.index.json" [components.storage_size] in_bytes = 23802816640

对照 model_cards.py 的ComponentInfo结构可以看出每个组件的语义：component_path是 HF 仓库内子目录，can_shard = true的组件（这里是 transformer）才会参与跨节点分片，safetensors_index_filename指定该组件的分片索引文件名。下载协调器（src/exo/download/coordinator.py）据此为每个组件独立规划分片任务。

3.5 capabilities 与推理能力标记

capabilities定义模型"能做什么"，当前文档与源码共同确认的取值：

• text：标准文本生成；
• thinking：支持思维链推理（CoT）；
• thinking_toggle：可通过enable_thinking参数开关思考模式（如上文 GLM-4.5-Air 卡）；
• image_edit：支持图像到图像编辑（如 FLUX.1-Kontext）。

3.6 安全说明

trust_remote_code涉及从 HF Hub 拉取并执行模型方自定义代码，风险明确。CONTRIBUTING 的安全原则是：默认关闭，仅当模型明确依赖远程代码时才开启。实现层面需要留意一个差异：ModelCard的 Pydantic 字段默认值在 model_cards.py 中声明为True，但自动从 HF 抓取生成卡片的路径（fetch_from_hf）显式写入trust_remote_code=False——也就是说，任何自动生成的卡片都默认不开远程代码，只有人工提交的模型卡才会开启该字段，提交时务必遵循"非必要不开"的原则。

四、API 适配器：让 exo 同时说 OpenAI、Claude、Ollama 的话

exo 通过适配器模式对外暴露多种 API 格式。适配器的职责是一条清晰的单向边界：把各 API 特有的请求格式转换成 exo 内部统一的TextGenerationTaskParams，再把内部推理产生的 token 流转换回该 API 特有的响应格式。

4.1 适配器架构（四步模式）

所有适配器遵循同一模式：

1. 将 API 特有请求转换为TextGenerationTaskParams；
2. 同时处理流式（SSE）与非流式两种响应生成；
3. 将内部TokenChunk对象转换为 API 特有格式；
4. 管理错误处理与边缘情况（如流中断、客户端断连）。

关键的类型边界是：内部系统（worker、runner、事件溯源层）只看到TextGenerationTaskParams和TokenChunk对象，任何 API 特有类型都不许跨越适配器边界。从源码看，这条边界被严格落实——以 src/exo/api/adapters/chat_completions.py 为例，其导入的内部类型只有exo.shared.types.chunks中的ErrorChunk/TokenChunk/ToolCallChunk（定义在 src/exo/shared/types/chunks.py）与exo.shared.types.text_generation中的TextGenerationTaskParams、InputMessage等，请求/响应 DTO 则全部来自 src/exo/api/types/。

一点需要指出的现状差异：CONTRIBUTING 中写的适配器目录是src/exo/master/adapters/、注册入口是src/exo/master/api.py，而当前代码库已将其迁移到 src/exo/api/adapters/，API 入口为 src/exo/api/main.py——贡献时以实际目录结构为准。

4.2 现有适配器

各适配器均有对应自动化测试，位于 src/exo/api/tests/，如test_chat_completions_stream.py、test_claude_api.py、test_claude_tool_use.py、test_openai_responses_api.py等——新增适配器时补齐同级别的流式/工具调用测试是惯例。

4.3 新增一个 API 适配器的标准步骤

按文档给出的模板，步骤如下：

1. 在src/exo/api/adapters/下新建适配器文件。

2. 实现请求转换函数：

def your_api_request_to_text_generation( request: YourAPIRequest, ) -> TextGenerationTaskParams: # Convert API request to internal format pass

3. 实现流式响应生成：

async def generate_your_api_stream( command_id: CommandId, chunk_stream: AsyncGenerator[TokenChunk | ErrorChunk | ToolCallChunk, None], ) -> AsyncGenerator[str, None]: # Convert internal chunks to API-specific streaming format pass

4. 实现非流式响应收集：

async def collect_your_api_response( command_id: CommandId, chunk_stream: AsyncGenerator[TokenChunk | ErrorChunk | ToolCallChunk, None], ) -> AsyncGenerator[str]: # Collect all chunks and return single response pass

5. 在 API 入口（当前为 src/exo/api/main.py）注册适配器的端点。

几个实现上的实战要点（从现有适配器代码可确认）：

• CommandId用于关联"哪一次内部命令产生了这条流"，流清理逻辑依赖它（参见 src/exo/api/tests/test_instance_deleted_stream_cleanup.py 对实例删除时流清理的验证）；
• chunk 流并非只有 token：ErrorChunk承载推理错误，ToolCallChunk承载解析出的工具调用，适配器必须区分处理，并在流末尾正确终止（test_finish_reason相关测试验证了 SSE 结束帧的finish_reason语义）；
• 推理模型的reasoning输出如何回传，由模型卡的reasoning_dialect与请求参数共同决定（见 src/exo/shared/types/text_generation.py 的resolve_reasoning_params及对应测试 src/exo/shared/tests/test_resolve_reasoning_params.py）。

各 API 的完整字段文档见 docs/api.md。

五、测试与提交

5.1 测试现状与要求

文档对测试的表述很坦率：exo 目前重度依赖手工测试，但正在快速改善。对贡献者的具体要求是：

• 提交变更前，同时测试变更前后的行为，用实际输出证明你的改动改善了系统行为；
• 用手头硬件做你力所能及的测试，需要协助时直接在 issue/PR 中提出；
• 尽可能补充自动化测试——项目正在系统性地提升自动化测试覆盖。

当前仓库的自动化测试已具备相当规模：单测使用 pytest（pyproject.toml中addopts = "-m 'not slow' --ignore=tests"，即默认只跑非slow标记的用例，并自动注入EXO_TESTS=1环境标记），覆盖模型卡应用逻辑（src/exo/shared/tests/test_apply/，含test_apply_custom_model_cards.py）、API 各适配器、MLX 引擎与放置算法；tests/ 目录还提供 1 节点、2 节点、4 节点集群与韧性（resilience）等端到端场景，适合作为多机改动的前后对照验证脚本。

5.2 提交流程

1. Fork 仓库；
2. 创建功能分支：git checkout -b feature/your-feature；
3. 提交改动：git commit -am 'Add some feature'；
4. 推送到分支：git push origin feature/your-feature；
5. 发起 PR 并遵循 PR 模板。

5.3 报告问题

发现 bug 或提出功能请求时，issue 中请包含：

• 清晰的问题/功能描述；
• 复现步骤（bug 类）；
• 期望行为 vs 实际行为；
• 你的环境信息（macOS 版本、硬件等）。

六、延伸阅读路径

想继续深入 exo 内部，建议按以下路径阅读当前仓库：

• 模型卡数据结构与缓存：src/exo/shared/models/model_cards.py（ModelCard、_CardCache、fetch_from_hf）；
• 内置模型卡样例库：resources/inference_model_cards/、resources/image_model_cards/；
• API 层入口与类型定义：src/exo/api/main.py、src/exo/api/types/、docs/api.md；
• 内部 chunk 协议（适配器的输出侧契约）：src/exo/shared/types/chunks.py；
• 跨节点放置决策（模型卡字段的消费方）：src/exo/master/placement.py 及其测试 src/exo/master/tests/test_placement.py；
• 多节点端到端测试：tests/test_2node.py、tests/test_resilience.py；
• 开发工具链：justfile、flake.nix、rust/exo_rs/。

总结来说，向 exo 贡献代码的核心链路是：uv 管理的 Python 3.13 环境 + nightly Rust 绑定 + npm 构建的 Svelte 仪表盘构成运行底座；TOML 模型卡是调度与下载体系的元数据契约，新增模型主要靠提交规范完整的卡片文件；API 适配器则是一条严格的类型边界，只要守住"TextGenerationTaskParams进、chunk 流出"的单向转换，就能让 exo 集群无缝接入任何新的 API 生态。

【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exo