贡献 Llama-Stack

我们希望让为本项目贡献变得尽可能简单和透明。

讨论 -> 问题 -> 拉取请求

我们积极欢迎您的拉取请求。但请阅读以下内容。这很大程度上受到了 Ghostty 的启发。

如果您有疑问，请开启一个讨论；我们稍后可以将其转换为问题。

我想贡献！

所有问题都具有可操作性（如果不是，请报告）。选择一个并开始处理。谢谢！如果您需要帮助或指导，请在问题上评论。对新贡献者特别友好的问题会打上“contributor friendly”标签。

我有一个 bug！

搜索问题跟踪器和讨论，查找类似问题。
如果您没有重现步骤，请开启讨论。
如果您有重现步骤，请开启问题。

我有一个功能想法！

开启讨论。

我已实现一个功能！

如果该功能已有对应的问题，请开启拉取请求。
如果该功能没有问题，请开启讨论并链接到您的分支。

我有一个问题！

开启讨论或使用 Discord。

开启拉取请求

Fork 仓库并从 main 分支创建您的分支。
如果您更改了 API，请更新文档。
确保测试套件通过。
确保您的代码使用 pre-commit 通过 lint 检查。
如果您尚未完成，请完成贡献者许可协议 (“CLA”)。
确保您的拉取请求遵循 conventional commits 格式。

贡献者许可协议 (“CLA”)

为了接受您的拉取请求，我们需要您提交 CLA。您只需完成一次即可为 Meta 的任何开源项目贡献。

在此完成您的 CLA：https://code.facebook.com/cla

问题

我们使用 GitHub issues 来跟踪公开的 bug。请确保您的描述清晰，并包含足够的说明以便重现问题。

Meta 对安全披露安全 bug 有赏金计划。在这种情况下，请按照该页面概述的流程进行，不要提交公开问题。

设置您的开发环境

我们使用 uv 来管理 Python 依赖项和虚拟环境。您可以按照此指南安装 uv。

您可以通过运行以下命令安装依赖项

cd llama-stack
uv sync --extra dev
uv pip install -e .
source .venv/bin/activate

[!注意] 您可以通过在项目根目录添加 .python-version 文件来指定 uv 使用特定版本的 Python。否则，uv 将根据 pyproject.toml 中的 requires-python 部分自动选择 Python 版本。有关更多信息，请参阅uv 文档中关于 Python 版本的部分。

请注意，您可以创建一个名为 .env 的 dotenv 文件，其中包含必要的环境变量

LLAMA_STACK_BASE_URL=http://localhost:8321
LLAMA_STACK_CLIENT_LOG=debug
LLAMA_STACK_PORT=8321
LLAMA_STACK_CONFIG=<provider-name>
TAVILY_SEARCH_API_KEY=
BRAVE_SEARCH_API_KEY=

然后，在运行客户端 SDK 测试时使用此 dotenv 文件，如下所示

uv run --env-file .env -- pytest -v tests/integration/inference/test_text_inference.py --text-model=meta-llama/Llama-3.1-8B-Instruct

Pre-commit Hooks

我们使用 pre-commit 来对您的代码运行 linting 和格式检查。您可以通过运行以下命令安装 pre-commit hooks

uv run pre-commit install

之后，pre-commit hooks 将在每次提交前自动运行。

或者，如果您不想安装 pre-commit hooks，您可以通过运行以下命令手动运行检查

uv run pre-commit run --all-files

[!注意] 在推送您的更改之前，请确保 pre-commit hooks 已成功通过。

运行测试

您可以在此处找到 Llama Stack 测试文档：这里。

向项目添加新的依赖项

要向项目添加新的依赖项，可以使用 uv 命令。例如，要向项目添加 foo，您可以运行

uv add foo
uv sync

编码风格

注释应提供对代码的有意义的见解。避免使用只描述下一步的填充注释，因为它们会创建不必要的混乱，docstrings 也是如此。
优先使用注释来澄清令人惊讶的行为和/或代码各部分之间的关系，而不是解释下一行代码的作用。
捕获异常时，首选使用特定的异常类型，而不是宽泛的捕获所有异常类型，例如 Exception。
错误消息应以“Failed to …”开头。
使用 4 个空格进行缩进，而不是 tab
使用 # noqa 来抑制样式或 linter 警告时，请包含注释解释绕过检查的理由。
使用 # type: ignore 来抑制 mypy 警告时，请包含注释解释绕过检查的理由。
请勿在代码库中使用 Unicode 字符。为了兼容性或可读性，首选仅使用 ASCII 字符。

常见任务

在贡献 Llama Stack 时，关于常见任务的一些提示

使用 `llama stack build`

构建堆栈镜像（conda / docker）将使用 llama-stack 和 llama-stack-client 包的生产版本。如果您正在开发中，并检出了 llama-stack 仓库，并且需要您的代码反映在堆栈镜像中，请在运行任何 llama CLI 命令时将 LLAMA_STACK_DIR 和 LLAMA_STACK_CLIENT_DIR 设置为相应的检出目录。

示例

cd work/
git clone https://github.com/meta-llama/llama-stack.git
git clone https://github.com/meta-llama/llama-stack-client-python.git
cd llama-stack
LLAMA_STACK_DIR=$(pwd) LLAMA_STACK_CLIENT_DIR=../llama-stack-client-python llama stack build --template <...>

更新提供商配置

如果您对提供商的配置进行了任何形式的更改（引入新的配置键，或更改模型等），您应该运行 ./scripts/distro_codegen.py 来重新生成各种 YAML 文件以及文档。您不应该手动更改 docs/source/.../distributions/ 文件，因为它们是自动生成的。

构建文档

如果您要更改 https://llama-stack.cn/en/latest/ 的文档，您可以使用以下命令构建文档并预览您的更改。您需要安装 Sphinx 和 readthedocs 主题。

cd docs
uv sync --extra docs

# This rebuilds the documentation pages.
uv run make html

# This will start a local server (usually at http://127.0.0.1:8000) that automatically rebuilds and refreshes when you make changes to the documentation.
uv run sphinx-autobuild source build/html --write-all

更新 API 文档

如果您修改或添加了新的 API 端点，请相应地更新 API 文档。您可以通过运行以下命令来完成

uv run --with ".[dev]" ./docs/openapi_generator/run_openapi_generator.sh

生成的 API 文档将位于 docs/_static/ 中。提交前务必仔细查看更改。

许可证

通过贡献 Llama，您同意您的贡献将根据此源代码树根目录中的 LICENSE 文件获得许可。

参见添加新的 API 提供商，其中描述了如何向堆栈添加新的 API 提供商。