Xinference 仓库 AI 编码代理协作指南从环境搭建、代码规范到 CI 与评审的完整实践手册【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference导读本文是面向在 Xinference 仓库中工作的 AI 编码代理以及人类开发者的完整协作指南系统梳理该仓库的模块划分、开发环境搭建、格式化与静态检查工具链、测试策略、前端与文档维护流程、模型运行时约定以及 CI 预期与 Git 评审规范。读完本文你将掌握一套可落地的仓库开发方法论既能用正确的命令快速搭建可编辑安装环境也能遵循统一的提交、测试与文档同步流程让每一次改动都符合项目约定并通过自动化检查。本文以仓库根目录的 CLAUDE.mdAI Agent Guidance为骨架结合 pyproject.toml、.pre-commit-config.yaml、.github/workflows/python.yaml、build_backend.py 与 build_web.py 等真实配置与源码对原文档逐节展开并补充底层实现依据。项目全景核心包与入口点Xinference 是一个用 Python 实现的模型服务项目覆盖语言LLM、嵌入embedding、重排rerank、图像、视频、音频及多模态模型。它对外暴露的能力包括CLI 命令xinference、xinference-local、xinference-supervisor、xinference-worker等Python 同步/异步客户端REST 与 OpenAI 兼容 API基于 xoscar 的分布式运行时基于 React 的 Web UI。按照 CLAUDE.md 的说明仓库主要目录与入口如下路径职责xinference/Python 主包xinference/deploy/cmdline.pyCLI 入口注册xinference、xinference-local、xinference-supervisor、xinference-worker等命令xinference/core/supervisor/worker 运行时与 actor 编排xinference/model/模型族family、引擎、内置模型规格与模型测试xinference/api/API 服务器与 OpenAI 兼容路由xinference/client/同步与异步 Python 客户端frontend/Next.js Web UIdoc/source/Sphinx 文档源.github/workflows/python.yaml主 lint 与测试 CI从 pyproject.toml 的[project.scripts]可以看到完整的 CLI 入口映射xinference、xinference-local、xinference-supervisor、xinference-worker、xinference-router、xinference-router-agent以及两个运维命令xinference-migrate-auth、xinference-reset-auth-password。这说明仓库在部署层面支持 supervisor/worker 分布式模式与独立的 router 部署形态动手前先定位好对应入口能显著降低理解成本。工作准则小而聚焦、兼容优先CLAUDE.md 的 Working Rules 部分定义了所有代码改动必须遵守的边界小而聚焦优先选择与当前模块风格一致的小改动避免在修复局部 bug 时进行大面积重构向后兼容公共 API 行为、请求/响应 schema、模型注册名与 CLI 标志默认保持稳定若破坏性变更不可避免必须记录原因并尽可能补充弃用deprecation行为第三方代码禁区除非任务明确涉及 vendored 代码否则不要编辑xinference/thirdparty/仓库将大量上游模型实现如 cosyvoice、f5_tts、fish_speech 等整体 vendor 进来见 xinference/thirdparty/测试随行行为变更必须新增或更新测试模型运行时改动优先放在受影响的模型族目录xinference/model/**/tests/下类型注解新 Python 代码尽量使用类型注解项目鼓励 PEP 484 风格文档即 API文档与示例被视为面向用户的 API命令行示例必须保持准确。这些规则在 CI 中有实际约束力。例如 .github/workflows/python.yaml 中 GPU 测试分组对xinference/thirdparty/*一律映射为 audio 组而对xinference/model/llm/*则触发 llm 组——改动落在哪个模块就决定了它需要跑哪一类测试这与改动贴近模块的约定一脉相承。环境搭建conda 环境与可编辑安装推荐本地开发环境如下来自 CLAUDE.mdconda create --name xinf python3.12 nodejs conda activate xinf pip install -e .[dev]几点关键前提需要特别注意构建后端会自动构建 Web UI仓库使用树内in-treePEP 517 构建后端。从 pyproject.toml 的[build-system]可以看到[build-system] requires [ setuptools77,82, setuptools-scm8, ] build-backend build_backend backend-path [.]build_backend.py在生成 wheel、sdist 与 editable 安装之前会执行三步前置动作见 build_backend.py 的_pre_build校验内置模型元数据读取xinference/model/llm/llm_family.json要求其为列表且每个 family 必须包含model_specs列表否则直接拒绝打包记录完整 git 版本将 40 位完整 SHA 写入xinference/_commit.py供/v1/cluster/versionAPI 使用优先取仓库 git HEADgit 归档场景则从.git_archival.txt提取node:行从 sdist 构建时保留已有记录构建 Web UI调用build_web.py执行npm ci与npm run build并把静态导出产物暂存到xinference/ui/web/dist/index.html使其随包发布、后端无需 Node 运行时即可服务。因此如果你只关心 Python 侧开发、不想要 Web UI 构建可以设置NO_WEB_UI1 pip install -e .[dev]build_web.py中对该环境变量的解析覆盖了0/false/no/off之外的所有非空取值CI 的测试环境正是用NO_WEB_UI: 1跳过 npm 构建以节省时间见 .github/workflows/python.yaml。setuptools 版本钉住Python 3.12 及以上版本在 CI 中会安装setuptools82如果打包或 editable 安装失败本地也应采用同样的钉住python -m pip install -U pip setuptools82这是因为[build-system]声明了setuptools77,82的依赖范围。Python 版本与可选依赖CI 支持 Python 3.10 至 3.14见 .github/workflows/python.yaml 的build_test_job矩阵项目要求的requires-python 3.10可选模型引擎以 extras 形式提供见 pyproject.toml 的[project.optional-dependencies]主要包括transformers、vllm、sglang、mlx、embedding、rerank、image、video、audio、llama_cpp、router、doc、dev、otel、intel、musa、benchmark、anthropic与聚合的all。例如仅需 LLM 的 transformers 后端可安装pip install -e .[transformers]macOS Metal 用户则关注mlxextra仅限sys_platformdarwin and platform_machinearm64。格式化与静态检查pre-commit 工具链项目的 Python 格式化与检查全部经由 pre-commit 管理pip install pre-commit pre-commit run --files modified-files若需要对标上游 main 做整分支检查pre-commit run --from-refupstream/main --to-refHEAD --all-files根据 .pre-commit-config.yaml配置的 hooks 及对应配置位置如下Hook作用配置位置black代码格式化25.1.0[tool.black]end-of-file-fixer / trailing-whitespace文件结尾与行尾空白清理pre-commit-hooks v5.0.0ruff-checklint 检查0.15.22[tool.ruff]、[tool.ruff.lint]isortimport 排序5.12.0profileblack[tool.isort]mypy类型检查--ignore-missing-imports且--follow-imports skip[tool.mypy]codespell拼写检查2.2.2[tool.codespell]值得注意的细节所有 hooks 都通过exclude排除xinference/thirdparty/与xinference/router/tokenizer_assets/下的代码避免对 vendored 代码做格式化或 lint 干预。pyproject.toml中[tool.ruff]的line-length 100并且[tool.ruff.lint]显式声明了从旧 setup.cfg 迁移过来的 flake8 规则集E/F/W 系列整体保持向后兼容的检查口径。Python 测试先聚焦、后全量测试策略的第一原则是先跑聚焦测试pytest -vv path/to/test_file.py近似 CI 风格的非 GPU 全量命令来自 CLAUDE.md与 .github/workflows/python.yaml 的build_test_job保持一致pytest --timeout3000 -W ignore::PendingDeprecationWarning -vv \ --cov-configpyproject.toml --cov-reportxml --covxinference \ --ignore xinference/core/tests/test_continuous_batching.py \ --ignore xinference/model/image/tests/test_stable_diffusion.py \ --ignore xinference/model/image/tests/test_got_ocr2.py \ --ignore xinference/model/audio/tests \ --ignore xinference/model/embedding/tests/test_integrated_embedding.py \ --ignore xinference/model/llm/transformers/tests/test_tensorizer.py \ --ignore xinference/model/llm/tests/test_llm_model.py \ --ignore xinference/model/llm/vllm \ --ignore xinference/model/llm/sglang \ --ignore xinference/client/tests/test_client.py \ --ignore xinference/client/tests/test_async_client.py \ --ignore xinference/model/llm/mlx \ xinference日常开发建议使用更窄的命令。原因写得很直白大量模型测试依赖重型依赖、GPU/Metal、网络访问或真实模型下载不适合在本地全量执行。这也是为什么 CI 把它拆成了多类作业见下文 CI 一节。从 pyproject.toml 的[tool.pytest.ini_options]可以看到asyncio_mode auto异步测试无需显式装饰器即可被识别覆盖率配置[tool.coverage.run]只统计xinference/*并排除测试文件。前端Next.js 静态导出与后端托管Web UI 位于frontend/是一个 Next.js 应用React TypeScript Tailwind CSS以静态导出方式构建并由 Python 后端从xinference/ui/web/dist提供服务build_web.py正是把npm run build的产物暂存到该目录。常用命令cd frontend npm ci npm run dev npm run build npx eslint .npm run format仅在你有意让 Prettier 全树改写时使用日常不应乱跑。前端侧的检查npm ci、npx eslint .、Prettier check会被 CI 的 lint 作业执行见 .github/workflows/python.yaml 的 lint 作业该作业还会验证静态导出产物frontend/out/index.html、frontend/out/404.html必须存在并且动态路由必须产出__shell__*占位页面随后运行xinference/api/tests/test_frontend_static.py与test_frontend_static_real_export.py验证后端能正确服务静态文件。文档维护Sphinx、i18n 与自动生成文档源位于doc/source/常见依赖包含在docextra 中pip install -e .[doc] cd doc make html维护规则来自 CLAUDE.md修改 CLI、API、部署行为或模型支持时必须同步更新doc/source中对应页面新增或修改英文文档时必须为doc/source/locale/*/LC_MESSAGES/下所有已有 locale 生成对应的 gettext 更新PO 改动要限定在受影响的消息内并用msgfmt --check --check-format校验每个被修改的目录然后执行python doc/build_i18n.py --all编译并在每个维护语言中构建受影响的页面以验证渲染结果doc/source/models/builtin/下的内置模型文档由doc/source/gen_docs.py自动生成禁止手工编辑。修改内置模型注册表或model_spec.json后应运行cd doc/source python gen_docs.py并提交生成的文档变更。PR 工作流.github/workflows/pr_auto_run_gen_docs.yaml只会为符合条件的同仓库chore/models-sync/*分支推送生成的文档其他分支与 fork PR 需要显式运行生成器不能依赖工作流代为更新 PR。这与构建后端的模型元数据校验build_backend.py中的_validate_builtin_model_specs形成闭环注册模型与文档生成同源、同步。模型与运行时约定CLAUDE.md 的 Model and Runtime Conventions 给出几条直接影响代码组织与运行行为的约定模型族逻辑归属保持在对应xinference/model/family/包内内置模型元数据改动要贴近既有 spec 与测试懒导入与可选依赖重型模型库只在需要处导入避免拖累无关安装这正是[project.optional-dependencies]拆分出众多 extras 的原因平台保护Linux-only、CUDA-only 与 macOS Metal/MLX 路径都要保留平台守卫如mlxextra 的sys_platformdarwin条件分布式运行时改动同时考虑本地模式与 supervisor/worker 模式OpenAI 兼容行为请求/响应字段与流式行为要对照既有 API 与客户端测试验证参见xinference/api/protocols/anthropic.py、xinference/api/routers/llm.py及xinference/client/下的测试。CI 预期三层作业体系主 CI 工作流 .github/workflows/python.yaml 由三类作业组成理解它们有助于预判一次改动会被哪些检查覆盖1. lint 作业在 ubuntu Python 3.10 上执行pre-commit run --all-files随后安装 Node.js 依赖并跑npx eslint .与前端静态导出构建再运行前端静态服务测试test_frontend_static.py、test_frontend_static_real_export.py。2. 构建与测试作业build_test_job矩阵覆盖 Linux 全版本3.10–3.14macOS 与 Windows 各测最小和最大支持版本3.10 与 3.14外加一个 macOS Metal 专项modulemetal安装mlx、mlx-lm、mlx-vlm、mlx-whisper等并跑xinference/model/llm/mlx/tests/与 MLX 音频测试。测试环境统一设置NO_WEB_UI: 1并用pytest --timeout3000与覆盖率参数跑前文给出的非 GPU 全量命令Python 3.12 会先钉住setuptools82。3. GPU 测试作业gpu_test_job跑在gpu-t4runner 上按 diff 检测changes 作业决定是否触发以及触发哪些分组。路径到分组的映射规则本身就是理解仓库模块耦合度的好材料xinference/model/audio/*→ audioxinference/model/image/*→ imagexinference/model/embedding/*|rerank/*→ embeddingxinference/model/llm/*|scheduler/*|test_continuous_batching.py→ llmxinference/thirdparty/*→ audiovendored 模型代码目前只涉及音频xinference/core/*、xinference/api/*、xinference/client/*、xinference/deploy/*任一改动 → 全量四个分组因为它们被每个模型族共享xinference/ui/*、xinference/model/video/*、xinference/model/flexible/*等不触发 GPU 测试匹配不到任何规则文档、示例等则不跑 GPU CI。GPU 作业还会恢复 ModelScope 模型缓存路径为~/.xinference/modelscope并使用XINFERENCE_MODEL_SRC: huggingface钉住模型源。每组 pytest 失败后会用--last-failed重试一次。简而言之改动属于哪个模块决定了它要经受哪一层检查在标记完成前至少要跑覆盖所改行为的最小有效验证命令并说明因环境成本或缺少硬件而未执行的更宽检查。Git 与评审卫生最后CLAUDE.md 对 Git 使用与代码评审提出了操作性要求提交范围保持提交与请求的改动范围一致不擅自回退除非被要求不要在现有 worktree 中重写或回退用户的改动worktree 隔离若当前 checkout 繁忙或处于无关分支使用独立 worktree并用语义化分支名fix/...、feat/...、docs/...评审去重在 PR 评审中先查看既有 GitHub review 线程避免重复评论。总结一份可执行的仓库协作清单把 CLAUDE.md 与仓库真实配置对照后可以得到一条完整的开发路径先用conda建环境并以pip install -e .[dev]做可编辑安装必要时NO_WEB_UI1跳过 Web UI 构建、Python 3.12 钉住setuptools82→ 用 pre-commit 保证格式与静态检查 → 先跑聚焦 pytest、再按需跑 CI 风格全量命令 → 涉及 CLI/API/部署/模型时同步更新doc/source并维护多语言 PO → 改动落在模型族时遵守懒导入与平台守卫约定 → 依据 CI 三层作业lint、跨版本构建测试、按 diff 分组的 GPU 测试验证 → 最后按 Git 卫生规范提交与评审。这套流程既有自动化工具的强约束也保留了环境成本与硬件限制下选择最小验证的务实空间是长期维护大型模型服务项目时非常值得借鉴的工程实践。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Xinference 仓库 AI 编码代理协作指南：从环境搭建、代码规范到 CI 与评审的完整实践手册
Xinference 仓库 AI 编码代理协作指南从环境搭建、代码规范到 CI 与评审的完整实践手册【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference导读本文是面向在 Xinference 仓库中工作的 AI 编码代理以及人类开发者的完整协作指南系统梳理该仓库的模块划分、开发环境搭建、格式化与静态检查工具链、测试策略、前端与文档维护流程、模型运行时约定以及 CI 预期与 Git 评审规范。读完本文你将掌握一套可落地的仓库开发方法论既能用正确的命令快速搭建可编辑安装环境也能遵循统一的提交、测试与文档同步流程让每一次改动都符合项目约定并通过自动化检查。本文以仓库根目录的 CLAUDE.mdAI Agent Guidance为骨架结合 pyproject.toml、.pre-commit-config.yaml、.github/workflows/python.yaml、build_backend.py 与 build_web.py 等真实配置与源码对原文档逐节展开并补充底层实现依据。项目全景核心包与入口点Xinference 是一个用 Python 实现的模型服务项目覆盖语言LLM、嵌入embedding、重排rerank、图像、视频、音频及多模态模型。它对外暴露的能力包括CLI 命令xinference、xinference-local、xinference-supervisor、xinference-worker等Python 同步/异步客户端REST 与 OpenAI 兼容 API基于 xoscar 的分布式运行时基于 React 的 Web UI。按照 CLAUDE.md 的说明仓库主要目录与入口如下路径职责xinference/Python 主包xinference/deploy/cmdline.pyCLI 入口注册xinference、xinference-local、xinference-supervisor、xinference-worker等命令xinference/core/supervisor/worker 运行时与 actor 编排xinference/model/模型族family、引擎、内置模型规格与模型测试xinference/api/API 服务器与 OpenAI 兼容路由xinference/client/同步与异步 Python 客户端frontend/Next.js Web UIdoc/source/Sphinx 文档源.github/workflows/python.yaml主 lint 与测试 CI从 pyproject.toml 的[project.scripts]可以看到完整的 CLI 入口映射xinference、xinference-local、xinference-supervisor、xinference-worker、xinference-router、xinference-router-agent以及两个运维命令xinference-migrate-auth、xinference-reset-auth-password。这说明仓库在部署层面支持 supervisor/worker 分布式模式与独立的 router 部署形态动手前先定位好对应入口能显著降低理解成本。工作准则小而聚焦、兼容优先CLAUDE.md 的 Working Rules 部分定义了所有代码改动必须遵守的边界小而聚焦优先选择与当前模块风格一致的小改动避免在修复局部 bug 时进行大面积重构向后兼容公共 API 行为、请求/响应 schema、模型注册名与 CLI 标志默认保持稳定若破坏性变更不可避免必须记录原因并尽可能补充弃用deprecation行为第三方代码禁区除非任务明确涉及 vendored 代码否则不要编辑xinference/thirdparty/仓库将大量上游模型实现如 cosyvoice、f5_tts、fish_speech 等整体 vendor 进来见 xinference/thirdparty/测试随行行为变更必须新增或更新测试模型运行时改动优先放在受影响的模型族目录xinference/model/**/tests/下类型注解新 Python 代码尽量使用类型注解项目鼓励 PEP 484 风格文档即 API文档与示例被视为面向用户的 API命令行示例必须保持准确。这些规则在 CI 中有实际约束力。例如 .github/workflows/python.yaml 中 GPU 测试分组对xinference/thirdparty/*一律映射为 audio 组而对xinference/model/llm/*则触发 llm 组——改动落在哪个模块就决定了它需要跑哪一类测试这与改动贴近模块的约定一脉相承。环境搭建conda 环境与可编辑安装推荐本地开发环境如下来自 CLAUDE.mdconda create --name xinf python3.12 nodejs conda activate xinf pip install -e .[dev]几点关键前提需要特别注意构建后端会自动构建 Web UI仓库使用树内in-treePEP 517 构建后端。从 pyproject.toml 的[build-system]可以看到[build-system] requires [ setuptools77,82, setuptools-scm8, ] build-backend build_backend backend-path [.]build_backend.py在生成 wheel、sdist 与 editable 安装之前会执行三步前置动作见 build_backend.py 的_pre_build校验内置模型元数据读取xinference/model/llm/llm_family.json要求其为列表且每个 family 必须包含model_specs列表否则直接拒绝打包记录完整 git 版本将 40 位完整 SHA 写入xinference/_commit.py供/v1/cluster/versionAPI 使用优先取仓库 git HEADgit 归档场景则从.git_archival.txt提取node:行从 sdist 构建时保留已有记录构建 Web UI调用build_web.py执行npm ci与npm run build并把静态导出产物暂存到xinference/ui/web/dist/index.html使其随包发布、后端无需 Node 运行时即可服务。因此如果你只关心 Python 侧开发、不想要 Web UI 构建可以设置NO_WEB_UI1 pip install -e .[dev]build_web.py中对该环境变量的解析覆盖了0/false/no/off之外的所有非空取值CI 的测试环境正是用NO_WEB_UI: 1跳过 npm 构建以节省时间见 .github/workflows/python.yaml。setuptools 版本钉住Python 3.12 及以上版本在 CI 中会安装setuptools82如果打包或 editable 安装失败本地也应采用同样的钉住python -m pip install -U pip setuptools82这是因为[build-system]声明了setuptools77,82的依赖范围。Python 版本与可选依赖CI 支持 Python 3.10 至 3.14见 .github/workflows/python.yaml 的build_test_job矩阵项目要求的requires-python 3.10可选模型引擎以 extras 形式提供见 pyproject.toml 的[project.optional-dependencies]主要包括transformers、vllm、sglang、mlx、embedding、rerank、image、video、audio、llama_cpp、router、doc、dev、otel、intel、musa、benchmark、anthropic与聚合的all。例如仅需 LLM 的 transformers 后端可安装pip install -e .[transformers]macOS Metal 用户则关注mlxextra仅限sys_platformdarwin and platform_machinearm64。格式化与静态检查pre-commit 工具链项目的 Python 格式化与检查全部经由 pre-commit 管理pip install pre-commit pre-commit run --files modified-files若需要对标上游 main 做整分支检查pre-commit run --from-refupstream/main --to-refHEAD --all-files根据 .pre-commit-config.yaml配置的 hooks 及对应配置位置如下Hook作用配置位置black代码格式化25.1.0[tool.black]end-of-file-fixer / trailing-whitespace文件结尾与行尾空白清理pre-commit-hooks v5.0.0ruff-checklint 检查0.15.22[tool.ruff]、[tool.ruff.lint]isortimport 排序5.12.0profileblack[tool.isort]mypy类型检查--ignore-missing-imports且--follow-imports skip[tool.mypy]codespell拼写检查2.2.2[tool.codespell]值得注意的细节所有 hooks 都通过exclude排除xinference/thirdparty/与xinference/router/tokenizer_assets/下的代码避免对 vendored 代码做格式化或 lint 干预。pyproject.toml中[tool.ruff]的line-length 100并且[tool.ruff.lint]显式声明了从旧 setup.cfg 迁移过来的 flake8 规则集E/F/W 系列整体保持向后兼容的检查口径。Python 测试先聚焦、后全量测试策略的第一原则是先跑聚焦测试pytest -vv path/to/test_file.py近似 CI 风格的非 GPU 全量命令来自 CLAUDE.md与 .github/workflows/python.yaml 的build_test_job保持一致pytest --timeout3000 -W ignore::PendingDeprecationWarning -vv \ --cov-configpyproject.toml --cov-reportxml --covxinference \ --ignore xinference/core/tests/test_continuous_batching.py \ --ignore xinference/model/image/tests/test_stable_diffusion.py \ --ignore xinference/model/image/tests/test_got_ocr2.py \ --ignore xinference/model/audio/tests \ --ignore xinference/model/embedding/tests/test_integrated_embedding.py \ --ignore xinference/model/llm/transformers/tests/test_tensorizer.py \ --ignore xinference/model/llm/tests/test_llm_model.py \ --ignore xinference/model/llm/vllm \ --ignore xinference/model/llm/sglang \ --ignore xinference/client/tests/test_client.py \ --ignore xinference/client/tests/test_async_client.py \ --ignore xinference/model/llm/mlx \ xinference日常开发建议使用更窄的命令。原因写得很直白大量模型测试依赖重型依赖、GPU/Metal、网络访问或真实模型下载不适合在本地全量执行。这也是为什么 CI 把它拆成了多类作业见下文 CI 一节。从 pyproject.toml 的[tool.pytest.ini_options]可以看到asyncio_mode auto异步测试无需显式装饰器即可被识别覆盖率配置[tool.coverage.run]只统计xinference/*并排除测试文件。前端Next.js 静态导出与后端托管Web UI 位于frontend/是一个 Next.js 应用React TypeScript Tailwind CSS以静态导出方式构建并由 Python 后端从xinference/ui/web/dist提供服务build_web.py正是把npm run build的产物暂存到该目录。常用命令cd frontend npm ci npm run dev npm run build npx eslint .npm run format仅在你有意让 Prettier 全树改写时使用日常不应乱跑。前端侧的检查npm ci、npx eslint .、Prettier check会被 CI 的 lint 作业执行见 .github/workflows/python.yaml 的 lint 作业该作业还会验证静态导出产物frontend/out/index.html、frontend/out/404.html必须存在并且动态路由必须产出__shell__*占位页面随后运行xinference/api/tests/test_frontend_static.py与test_frontend_static_real_export.py验证后端能正确服务静态文件。文档维护Sphinx、i18n 与自动生成文档源位于doc/source/常见依赖包含在docextra 中pip install -e .[doc] cd doc make html维护规则来自 CLAUDE.md修改 CLI、API、部署行为或模型支持时必须同步更新doc/source中对应页面新增或修改英文文档时必须为doc/source/locale/*/LC_MESSAGES/下所有已有 locale 生成对应的 gettext 更新PO 改动要限定在受影响的消息内并用msgfmt --check --check-format校验每个被修改的目录然后执行python doc/build_i18n.py --all编译并在每个维护语言中构建受影响的页面以验证渲染结果doc/source/models/builtin/下的内置模型文档由doc/source/gen_docs.py自动生成禁止手工编辑。修改内置模型注册表或model_spec.json后应运行cd doc/source python gen_docs.py并提交生成的文档变更。PR 工作流.github/workflows/pr_auto_run_gen_docs.yaml只会为符合条件的同仓库chore/models-sync/*分支推送生成的文档其他分支与 fork PR 需要显式运行生成器不能依赖工作流代为更新 PR。这与构建后端的模型元数据校验build_backend.py中的_validate_builtin_model_specs形成闭环注册模型与文档生成同源、同步。模型与运行时约定CLAUDE.md 的 Model and Runtime Conventions 给出几条直接影响代码组织与运行行为的约定模型族逻辑归属保持在对应xinference/model/family/包内内置模型元数据改动要贴近既有 spec 与测试懒导入与可选依赖重型模型库只在需要处导入避免拖累无关安装这正是[project.optional-dependencies]拆分出众多 extras 的原因平台保护Linux-only、CUDA-only 与 macOS Metal/MLX 路径都要保留平台守卫如mlxextra 的sys_platformdarwin条件分布式运行时改动同时考虑本地模式与 supervisor/worker 模式OpenAI 兼容行为请求/响应字段与流式行为要对照既有 API 与客户端测试验证参见xinference/api/protocols/anthropic.py、xinference/api/routers/llm.py及xinference/client/下的测试。CI 预期三层作业体系主 CI 工作流 .github/workflows/python.yaml 由三类作业组成理解它们有助于预判一次改动会被哪些检查覆盖1. lint 作业在 ubuntu Python 3.10 上执行pre-commit run --all-files随后安装 Node.js 依赖并跑npx eslint .与前端静态导出构建再运行前端静态服务测试test_frontend_static.py、test_frontend_static_real_export.py。2. 构建与测试作业build_test_job矩阵覆盖 Linux 全版本3.10–3.14macOS 与 Windows 各测最小和最大支持版本3.10 与 3.14外加一个 macOS Metal 专项modulemetal安装mlx、mlx-lm、mlx-vlm、mlx-whisper等并跑xinference/model/llm/mlx/tests/与 MLX 音频测试。测试环境统一设置NO_WEB_UI: 1并用pytest --timeout3000与覆盖率参数跑前文给出的非 GPU 全量命令Python 3.12 会先钉住setuptools82。3. GPU 测试作业gpu_test_job跑在gpu-t4runner 上按 diff 检测changes 作业决定是否触发以及触发哪些分组。路径到分组的映射规则本身就是理解仓库模块耦合度的好材料xinference/model/audio/*→ audioxinference/model/image/*→ imagexinference/model/embedding/*|rerank/*→ embeddingxinference/model/llm/*|scheduler/*|test_continuous_batching.py→ llmxinference/thirdparty/*→ audiovendored 模型代码目前只涉及音频xinference/core/*、xinference/api/*、xinference/client/*、xinference/deploy/*任一改动 → 全量四个分组因为它们被每个模型族共享xinference/ui/*、xinference/model/video/*、xinference/model/flexible/*等不触发 GPU 测试匹配不到任何规则文档、示例等则不跑 GPU CI。GPU 作业还会恢复 ModelScope 模型缓存路径为~/.xinference/modelscope并使用XINFERENCE_MODEL_SRC: huggingface钉住模型源。每组 pytest 失败后会用--last-failed重试一次。简而言之改动属于哪个模块决定了它要经受哪一层检查在标记完成前至少要跑覆盖所改行为的最小有效验证命令并说明因环境成本或缺少硬件而未执行的更宽检查。Git 与评审卫生最后CLAUDE.md 对 Git 使用与代码评审提出了操作性要求提交范围保持提交与请求的改动范围一致不擅自回退除非被要求不要在现有 worktree 中重写或回退用户的改动worktree 隔离若当前 checkout 繁忙或处于无关分支使用独立 worktree并用语义化分支名fix/...、feat/...、docs/...评审去重在 PR 评审中先查看既有 GitHub review 线程避免重复评论。总结一份可执行的仓库协作清单把 CLAUDE.md 与仓库真实配置对照后可以得到一条完整的开发路径先用conda建环境并以pip install -e .[dev]做可编辑安装必要时NO_WEB_UI1跳过 Web UI 构建、Python 3.12 钉住setuptools82→ 用 pre-commit 保证格式与静态检查 → 先跑聚焦 pytest、再按需跑 CI 风格全量命令 → 涉及 CLI/API/部署/模型时同步更新doc/source并维护多语言 PO → 改动落在模型族时遵守懒导入与平台守卫约定 → 依据 CI 三层作业lint、跨版本构建测试、按 diff 分组的 GPU 测试验证 → 最后按 Git 卫生规范提交与评审。这套流程既有自动化工具的强约束也保留了环境成本与硬件限制下选择最小验证的务实空间是长期维护大型模型服务项目时非常值得借鉴的工程实践。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考