exo 如何新建 TOML 模型卡必填字段、可选 capabilities 与 trust_remote_code 设置【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exoexo 用 TOML 格式的模型卡model card来描述一个模型的元数据与能力模型能否被 exo 识别、能否参与放置调度都取决于这张卡。当你需要让 exo 支持一个仓库内置目录里还没有的模型比如 HuggingFace 上的一个新 mlx-community 模型时最直接的方式是手写一份 TOML 模型卡放入用户自定义模型卡目录本文覆盖这条路径卡放在哪里、必填字段怎么写、capabilities有哪些取值、以及trust_remote_code的安全设置。模型卡放在哪个目录exo 的模型卡按用途分三个目录见 CONTRIBUTING.md 的 Model Cards 一节resources/inference_model_cards/内置文本生成模型的卡resources/image_model_cards/内置图像生成模型的卡用户自定义模型卡目录存放你自己新增的卡。给现有安装新增模型时卡应写入用户自定义目录而不是修改内置目录。自定义目录的路径README.md 在 Linux 下给出的是~/.local/share/exo/custom_model_cards/exo 遵循 XDG 规范可通过$XDG_DATA_HOME等环境变量覆盖CONTRIBUTING.md 中写作~/.exo/custom_model_cards/。两处文档路径不一致以你实际安装平台的数据目录为准。该目录代码中使用rglob(*.toml)遍历下的所有*.toml都会被加载文件名不必特殊但仓库内置卡的命名规律可以参考mlx-community--DeepSeek-V3.1-4bit.toml 用双短横线--代替 model_id 里的斜杠这是自动保存路径采用的 model_id 归一化结果。TOML 模型卡怎么写CONTRIBUTING.md 给出的标准模板如下Llama 1B 示例可整体复制后按你的模型修改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仓库内置的 mlx-community--DeepSeek-V3.1-4bit.toml 展示了一张更完整的卡除了模板字段外还包含num_key_value_heads 128 reasoning_dialect post_last_user context_length 131072 backends [MlxMetal, MlxCuda, MlxCpu] [sampling_defaults] temperature 0.6 top_p 0.95其中num_key_value_heads、context_length、reasoning_dialect、sampling_defaults在代码里都有对应字段定义见 model_cards.py 的ModelCard。backends需要特别注意ModelCard中它是无默认值的必填字段而 CONTRIBUTING 模板并未展示这一项——按仓库现有卡的写法补齐例如backends [MlxMetal, MlxCuda, MlxCpu]取自上述 DeepSeek 卡的实际取值。必填字段清单按 CONTRIBUTING.md 的 Required Fields字段含义model_idHuggingFace 模型标识如mlx-community/DeepSeek-V3.1-4bitn_layersTransformer 层数hidden_size隐藏层维度supports_tensor模型是否支持张量并行tasks支持的任务列表取值TextGeneration、TextToImage、ImageToImagefamily模型家族如llama、deepseek、qwenquantization量化级别如4bit、8bit、bf16base_model人类可读的基座模型名capabilities能力列表如[text]、[text, thinking]再加上代码层面必填的backends和表示存储大小的[storage_size] in_bytes表模板中已含就是一张能通过校验的最小卡。n_layers、hidden_size在代码里是PositiveIntstorage_size.in_bytes是模型文件总字节数。capabilities 可选值capabilities字段定义模型能做什么CONTRIBUTING.md 列出的取值text标准文本生成thinking模型支持思维链推理thinking_togglethinking 可通过enable_thinking参数开启/关闭image_edit支持图生图编辑FLUX.1-Kontext。以仓库中 DeepSeek-V3.1-4bit 的卡 为例capabilities [text, thinking, thinking_toggle]并配合reasoning_dialect post_last_user声明其推理方言。trust_remote_code 怎么设置trust_remote_code是可选布尔字段控制是否允许该模型执行远程代码。两份文档的安全口径一致CONTRIBUTING.md默认false安全考虑只有当模型明确要求从 HuggingFace hub 执行远程代码时才启用README.md 的 Security Note自定义模型如需trust_remote_code必须显式启用默认 false仅在信任该模型的远程代码时开启。代码里有一个值得留意的细节ModelCard的 pydantic 字段默认值是True见 model_cards.py而通过 API 自动抓取模型时生成的卡会显式写入trust_remote_codeFalsemodel_cards.py 的fetch_from_hf。因此手写 TOML 时不要依赖“不写就是 false”的假设应显式写trust_remote_code false确实需要远程代码的模型再写trust_remote_code true。验证卡是否被加载启动 exo。从源码运行的前提是安装 uvbrew install uv然后uv run exo见 CONTRIBUTING.md 的 Getting Started。用 README 给出的模型列表接口查询curl http://localhost:52415/models新模型的model_id出现在返回中说明卡加载成功只列已下载模型可用curl http://localhost:52415/models?statusdownloaded。如果模型没有出现检查字段加载代码_load_cards_from_dirmodel_cards.py对校验失败ValidationError或 TOML 解析失败TOMLKitError的文件会跳过并输出failed to validate model card at 路径的 warning。常见原因是漏写backends、tasks用了非枚举值、或n_layers/hidden_size不是正整数。可选替代用 API 自动生成卡如果模型在 HuggingFace 上可直接抓取不必手写全部字段。README.md 提供/models/add端点model_id换成你的 HF 模型 IDcurl -X POST http://localhost:52415/models/add \ -H Content-Type: application/json \ -d { model_id: mlx-community/my-custom-model }该路径会抓取模型的config.json和 safetensors 索引得到层数、hidden_size、存储大小等自动把卡保存进自定义模型卡目录fetch_from_hfsave_to_custom_dir见 model_cards.py。生成的卡trust_remote_code固定写为falsebackends填全部后端取值由放置环节再决定实际可用性。手写 TOML 与这条自动路径二选一即可自动路径适合结构简单的 HF 模型手写路径适合需要精确指定capabilities、reasoning_dialect、sampling_defaults的模型。限制图像模型的卡放在resources/image_model_cards/tasks使用TextToImage/ImageToImage图像卡默认只在环境变量EXO_ENABLE_IMAGE_MODELStrue时才会进入模型列表默认false见 constants.py 与 model_cards.py本文的手写流程以文本生成模型TextGeneration为主。自定义卡目录路径在 CONTRIBUTING 与 README 两处文档不一致~/.exo/custom_model_cards/与~/.local/share/exo/custom_model_cards/新增卡前先在对应平台确认实际数据目录。修改卡文件后若列表里仍是旧内容可改用/models接口核对当前缓存结果自动抓取生成的卡如需修正字段直接在自定义目录里编辑对应 TOML 即可。【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 exo 如何新建 TOML 模型卡？必填字段、可选 capabilities 与 trust_remote_code 设置
exo 如何新建 TOML 模型卡必填字段、可选 capabilities 与 trust_remote_code 设置【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exoexo 用 TOML 格式的模型卡model card来描述一个模型的元数据与能力模型能否被 exo 识别、能否参与放置调度都取决于这张卡。当你需要让 exo 支持一个仓库内置目录里还没有的模型比如 HuggingFace 上的一个新 mlx-community 模型时最直接的方式是手写一份 TOML 模型卡放入用户自定义模型卡目录本文覆盖这条路径卡放在哪里、必填字段怎么写、capabilities有哪些取值、以及trust_remote_code的安全设置。模型卡放在哪个目录exo 的模型卡按用途分三个目录见 CONTRIBUTING.md 的 Model Cards 一节resources/inference_model_cards/内置文本生成模型的卡resources/image_model_cards/内置图像生成模型的卡用户自定义模型卡目录存放你自己新增的卡。给现有安装新增模型时卡应写入用户自定义目录而不是修改内置目录。自定义目录的路径README.md 在 Linux 下给出的是~/.local/share/exo/custom_model_cards/exo 遵循 XDG 规范可通过$XDG_DATA_HOME等环境变量覆盖CONTRIBUTING.md 中写作~/.exo/custom_model_cards/。两处文档路径不一致以你实际安装平台的数据目录为准。该目录代码中使用rglob(*.toml)遍历下的所有*.toml都会被加载文件名不必特殊但仓库内置卡的命名规律可以参考mlx-community--DeepSeek-V3.1-4bit.toml 用双短横线--代替 model_id 里的斜杠这是自动保存路径采用的 model_id 归一化结果。TOML 模型卡怎么写CONTRIBUTING.md 给出的标准模板如下Llama 1B 示例可整体复制后按你的模型修改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仓库内置的 mlx-community--DeepSeek-V3.1-4bit.toml 展示了一张更完整的卡除了模板字段外还包含num_key_value_heads 128 reasoning_dialect post_last_user context_length 131072 backends [MlxMetal, MlxCuda, MlxCpu] [sampling_defaults] temperature 0.6 top_p 0.95其中num_key_value_heads、context_length、reasoning_dialect、sampling_defaults在代码里都有对应字段定义见 model_cards.py 的ModelCard。backends需要特别注意ModelCard中它是无默认值的必填字段而 CONTRIBUTING 模板并未展示这一项——按仓库现有卡的写法补齐例如backends [MlxMetal, MlxCuda, MlxCpu]取自上述 DeepSeek 卡的实际取值。必填字段清单按 CONTRIBUTING.md 的 Required Fields字段含义model_idHuggingFace 模型标识如mlx-community/DeepSeek-V3.1-4bitn_layersTransformer 层数hidden_size隐藏层维度supports_tensor模型是否支持张量并行tasks支持的任务列表取值TextGeneration、TextToImage、ImageToImagefamily模型家族如llama、deepseek、qwenquantization量化级别如4bit、8bit、bf16base_model人类可读的基座模型名capabilities能力列表如[text]、[text, thinking]再加上代码层面必填的backends和表示存储大小的[storage_size] in_bytes表模板中已含就是一张能通过校验的最小卡。n_layers、hidden_size在代码里是PositiveIntstorage_size.in_bytes是模型文件总字节数。capabilities 可选值capabilities字段定义模型能做什么CONTRIBUTING.md 列出的取值text标准文本生成thinking模型支持思维链推理thinking_togglethinking 可通过enable_thinking参数开启/关闭image_edit支持图生图编辑FLUX.1-Kontext。以仓库中 DeepSeek-V3.1-4bit 的卡 为例capabilities [text, thinking, thinking_toggle]并配合reasoning_dialect post_last_user声明其推理方言。trust_remote_code 怎么设置trust_remote_code是可选布尔字段控制是否允许该模型执行远程代码。两份文档的安全口径一致CONTRIBUTING.md默认false安全考虑只有当模型明确要求从 HuggingFace hub 执行远程代码时才启用README.md 的 Security Note自定义模型如需trust_remote_code必须显式启用默认 false仅在信任该模型的远程代码时开启。代码里有一个值得留意的细节ModelCard的 pydantic 字段默认值是True见 model_cards.py而通过 API 自动抓取模型时生成的卡会显式写入trust_remote_codeFalsemodel_cards.py 的fetch_from_hf。因此手写 TOML 时不要依赖“不写就是 false”的假设应显式写trust_remote_code false确实需要远程代码的模型再写trust_remote_code true。验证卡是否被加载启动 exo。从源码运行的前提是安装 uvbrew install uv然后uv run exo见 CONTRIBUTING.md 的 Getting Started。用 README 给出的模型列表接口查询curl http://localhost:52415/models新模型的model_id出现在返回中说明卡加载成功只列已下载模型可用curl http://localhost:52415/models?statusdownloaded。如果模型没有出现检查字段加载代码_load_cards_from_dirmodel_cards.py对校验失败ValidationError或 TOML 解析失败TOMLKitError的文件会跳过并输出failed to validate model card at 路径的 warning。常见原因是漏写backends、tasks用了非枚举值、或n_layers/hidden_size不是正整数。可选替代用 API 自动生成卡如果模型在 HuggingFace 上可直接抓取不必手写全部字段。README.md 提供/models/add端点model_id换成你的 HF 模型 IDcurl -X POST http://localhost:52415/models/add \ -H Content-Type: application/json \ -d { model_id: mlx-community/my-custom-model }该路径会抓取模型的config.json和 safetensors 索引得到层数、hidden_size、存储大小等自动把卡保存进自定义模型卡目录fetch_from_hfsave_to_custom_dir见 model_cards.py。生成的卡trust_remote_code固定写为falsebackends填全部后端取值由放置环节再决定实际可用性。手写 TOML 与这条自动路径二选一即可自动路径适合结构简单的 HF 模型手写路径适合需要精确指定capabilities、reasoning_dialect、sampling_defaults的模型。限制图像模型的卡放在resources/image_model_cards/tasks使用TextToImage/ImageToImage图像卡默认只在环境变量EXO_ENABLE_IMAGE_MODELStrue时才会进入模型列表默认false见 constants.py 与 model_cards.py本文的手写流程以文本生成模型TextGeneration为主。自定义卡目录路径在 CONTRIBUTING 与 README 两处文档不一致~/.exo/custom_model_cards/与~/.local/share/exo/custom_model_cards/新增卡前先在对应平台确认实际数据目录。修改卡文件后若列表里仍是旧内容可改用/models接口核对当前缓存结果自动抓取生成的卡如需修正字段直接在自定义目录里编辑对应 TOML 即可。【免费下载链接】exoRun frontier AI locally.项目地址: https://gitcode.com/GitHub_Trending/exo8/exo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考