11.2 · 依赖管理（Dependency Management）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节11.2 状态全文译文模块接口与服务契约、界面与交互、模型调用与提供方适配、系统架构

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Dependency Management 上一章11.1 下一章11.3

源码线索

.github/workflows/nightly-external-dependency-unit-tests.yml
.pre-commit-config.yaml
backend/onyx/llm/litellm_singleton/monkey_patches.py
backend/pytest.ini
backend/requirements/README.md
backend/requirements/default.txt
backend/requirements/dev.txt
backend/requirements/ee.txt
backend/requirements/model_server.txt
backend/tests/external_dependency_unit/conftest.py

模块标签

接口与服务契约
界面与交互
模型调用与提供方适配
系统架构
测试、发布与运维

章节正文

依赖管理

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/11.2-dependency-management

依赖管理

概述

Onyx 代码库使用 uv 作为 Python 依赖管理器，pyproject.toml 是所有后端和模型服务器依赖的唯一真实来源。该系统确保了开发环境、持续集成（CI）和生产 Docker 环境之间的环境可重现性。对于前端，则使用标准的 npm 配合 package-lock.json。通过自动化的 pre-commit 钩子，可以确保这些包管理器与导出的需求文件之间的一致性。

来源： pyproject.toml:1-246, backend/requirements/default.txt:1-2, backend/requirements/README.md:5-16

系统架构

依赖管理架构由真实来源层、用于解析的统一锁定层以及用于 Docker 兼容性的导出层组成。

Python 依赖流程

Onyx · Python 依赖流程 · 图 1

来源： pyproject.toml:5-195, uv.lock:1-15, .pre-commit-config.yaml:7-65, backend/requirements/README.md:18-30

依赖组织

Python 组

依赖项被划分为逻辑组，以最小化特定服务的攻击面和镜像大小。例如，模型服务器不包含像 psycopg2 这样的数据库驱动程序。Onyx 使用 uv 覆盖来解决由上游包（如 litellm）引入的版本冲突。

组	定义位置	用途	关键包
核心/共享	`[project.dependencies]`	所有 Python 服务共享	`fastapi`、`litellm`、`pydantic`、`openai`、`sentry-sdk`
后端	`backend` 组	主 API、工作器和连接器	`SQLAlchemy`、`alembic`、`celery`、`beautifulsoup4`、`playwright`
模型服务器	`model_server` 组	机器学习推理和嵌入逻辑	`torch`、`transformers`、`sentence-transformers`、`accelerate`
开发	`dev` 组	代码检查、测试和本地工具	`black`、`ruff`、`pytest`、`pre-commit`、`onyx-devtools`
企业版	`ee` 组	仅限企业版的功能	`posthog`

来源： pyproject.toml:10-195, pyproject.toml:202-216, uv.lock:17-32

前端依赖

Next.js 前端通过 web/package.json 管理依赖。它使用标准的 npm 版本控制，并通过锁文件确保一致性。

Onyx · 前端依赖 · 图 2

来源： .pre-commit-config.yaml:140-155

自动同步和 Pre-commit 钩子

Onyx 使用 pre-commit 来确保 uv.lock 和 requirements/*.txt 文件永远不会与 pyproject.toml 发生偏离。

Python 同步钩子

以下钩子在 .pre-commit-config.yaml 中配置：

uv-lock：如果 pyproject.toml 发生变化，则更新 uv.lock。[.pre-commit-config.yaml:12-12]
uv-export：使用特定的组参数（例如 --group backend）重新生成四个 backend/requirements/*.txt 文件。[.pre-commit-config.yaml:13-60]
uv-sync：自动同步本地环境。[.pre-commit-config.yaml:11-11]
uv-run：执行质量检查，如 ruff、black 和 ty。[.pre-commit-config.yaml:61-84]

前端同步钩子

npm-install：在修改 package.json 的 Git 操作（post-checkout、post-merge、post-rewrite）后，自动在 web/ 目录中运行 npm install --no-save。[.pre-commit-config.yaml:140-147]
npm-install-check：通过运行 npm install --package-lock-only 确保 web/package-lock.json 已更新。[.pre-commit-config.yaml:148-155]
typescript-check：使用 tsgo（TypeScript 的原生 Go 编译器）进行高性能类型检查。[.pre-commit-config.yaml:160-166]

来源： .pre-commit-config.yaml:1-166

操作工作流

手动重新生成

虽然 pre-commit 处理了大多数任务，但开发者可以使用 uv export 命令手动触发导出。这些命令使用 --no-emit-project 和 --no-default-groups 标志来创建干净的需求文件。

uv lock
uv export --no-emit-project --no-default-groups --group backend -o backend/requirements/default.txt
uv export --no-emit-project --no-default-groups --group dev -o backend/requirements/dev.txt

来源： backend/requirements/README.md:63-71, backend/requirements/default.txt:1-2

补丁和覆盖

系统通过 tool.uv.override-dependencies 处理复杂的依赖交互。这专门用于放宽来自像 litellm 这样的包的精确版本锁定，否则这些锁定会强制回退传递依赖（如 aiohttp 或 pydantic）的版本。

来源： pyproject.toml:196-216, uv.lock:18-32

关键文件及其作用

文件	作用
`pyproject.toml`	真实来源。定义所有 Python 依赖项、组和工具配置。`[pyproject.toml:1-246`]
`uv.lock`	锁文件。所有组中所有 Python 包的确定性解析。`[uv.lock:1-15`]
`backend/requirements/default.txt`	导出的生产依赖。为后端组自动生成。`[backend/requirements/default.txt:1-3`]
`backend/requirements/model_server.txt`	机器学习栈依赖。为 model_server 组自动生成。`[backend/requirements/model_server.txt:1-3`]
`.pre-commit-config.yaml`	自动化控制器。协调源文件和锁文件之间的同步。`[.pre-commit-config.yaml:6-15`]

来源： pyproject.toml:1-246, uv.lock:1-15, backend/requirements/README.md:21-30, .pre-commit-config.yaml:6-15