企业官网建设流程全解析

SpacetimeDB LLM 基准测试工具cargo llm开发与使用完全指南

【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB

本文以 SpacetimeDB 仓库中的 docs/DEVELOP.md 为核心骨架，系统讲解仓库内置 LLM 代码生成基准测试工具（cargo llm）的环境配置、基准套件结构、上下文构建机制与常见问题排查。该工具用于自动评估 OpenAI、Anthropic、Google、xAI、DeepSeek 等多家 LLM 供应商在 SpacetimeDB 模块（Rust / C# / TypeScript）代码生成上的能力，是 CI 中驱动"GPT-5 等模型生成模块代码 → 发布到本地 SpacetimeDB → 编译校验并打分"全流程的测试框架。读完本文，你将掌握如何配置本地开发环境、运行与筛选基准任务、新建自定义基准用例，以及理解上下文（Context）如何按语言过滤后喂给 LLM 的底层原理。

1. 前置条件（Prerequisites）

在使用cargo llm前，需要满足以下环境约束：

• 必须从仓库根目录运行：cargo llm及所有相关命令都必须在工作区根目录（即本仓库目录）执行，因为工具依赖整个 workspace 的 crate 构建产物与相对路径布局。tools/xtask-llm-benchmark已注册为 Cargo.toml 的 workspace 成员（见members列表中的"tools/xtask-llm-benchmark"），因此可以直接以 xtask 风格通过cargo llm调用。
• TypeScript 基准需要先构建 SDK：在crates/bindings-typescript目录下先执行pnpm build。Rust 与 C# 使用本地 crate（属于 workspace 的一部分），构建时会自动随 workspace 编译，无需额外步骤。
• Windows（nvm4w）：如果运行 TypeScript 基准时找不到pnpm，需要设置NODEJS_DIR环境变量指向你的 Node.js bin 目录，例如C:\nvm\v20.10.0。

2. 快速检查与修复（Quick Checks & Fixes）

当 CI 因哈希过期或结果陈旧而卡住时，可以用单条命令快速解锁：

cargo llm ci-quickfix

该命令的执行内容如下：

1. 仅为GPT-5运行 Rust 的rustdoc_json通道（pass）；
2. 仅为GPT-5运行 C# 的docs通道；
3. 写回更新后的结果与汇总文件。

注意：ci-quickfix不是完整的基准套件，它只做最小化的 Rust + C# 通道重跑，用于让 CI 通过。本地运行需要 OpenAI API key；任何 SpacetimeDB 成员也可以在 PR 上评论/update-llm-benchmark来触发 CI 任务完成同样的工作。

模型 ID 必须匹配配置的路由：传入--models的模型 ID 必须与 model_routes.rs 中配置的路由一致，例如"openai:gpt-5"。源码中ModelRoute结构体同时携带display_name（报表中的人类可读标签）、vendor（API 族）、api_model（供应商直连 API 期望的模型 ID）与可选的openrouter_model（走 OpenRouter 网关时的模型 ID）。

Spacetime CLI

基准跑完 LLM 生成的代码后，会通过spacetimeCLI 发布模块进行校验：

spacetime publish -c -y --server <name> <db>

前提条件：

• spacetime已加入PATH；
• 目标 server 可达且在运行中。

从源码看，发布目标 DB 名称通过 bench/utils.rs 中的sanitize_db_name、run_scope_tag、golden_db_name等函数生成：名称会被统一转为小写、非法字符替换为-、连续短横线折叠，并以db前缀兜底，保证不同mode + vendor + model组合（scope）与 golden 答案使用相互隔离的数据库实例。

3. 环境变量

下表列出了工具的默认/推荐开发值。源码 bench/utils.rs 中的解析逻辑确认：LLM_DEBUG与LLM_DEBUG_VERBOSE接受1/true/yes三种真值；并发数通过parse().ok()读取，解析失败时回落到内置默认值。

* 仅当你要在本地运行该供应商时才必需。

规范开发环境配置块（shell）

可复制到你的 shell profile：

OPENAI_API_KEY= OPENAI_BASE_URL=https://api.openai.com/ ANTHROPIC_API_KEY= ANTHROPIC_BASE_URL=https://api.anthropic.com GOOGLE_API_KEY= GOOGLE_BASE_URL=https://generativelanguage.googleapis.com XAI_API_KEY= XAI_BASE_URL=https://api.x.ai DEEPSEEK_API_KEY= DEEPSEEK_BASE_URL=https://api.deepseek.com META_API_KEY= META_BASE_URL=https://openrouter.ai/api/v1 SPACETIME_SERVER="local" LLM_DEBUG=true LLM_DEBUG_VERBOSE=false LLM_BENCH_CONCURRENCY=20 LLM_BENCH_ROUTE_CONCURRENCY=4

规范开发环境配置块（Windows PowerShell）

$env:SPACETIME_SERVER="local" $env:LLM_DEBUG="true" $env:LLM_DEBUG_VERBOSE="false" $env:LLM_BENCH_CONCURRENCY="20" $env:LLM_BENCH_ROUTE_CONCURRENCY="4"

LLM 供应商：Key 与 Base URL

这些配置与仓库中实际接线的客户端一一对应：OpenAiClient、AnthropicClient、GoogleGeminiClient、XaiGrokClient、DeepSeekClient、MetaLlamaClient，客户端实现位于 llm/clients 目录下。

额外并发控制（源码 bench/utils.rs 支持但文档未列出的三个变量，可视为进阶调优项）：

4. 基准套件（Benchmark Suite）

结果目录：docs/llms。

结果存储

基准结果通过 spacetime-web API 上传到远程 PostgreSQL 数据库。设置LLM_BENCHMARK_UPLOAD_URL与LLM_BENCHMARK_API_KEY后，每个基准批次运行结束后会自动上传；使用--dry-run可跳过上传。

源码 api/client.rs 进一步给出了接口细节：

• POST /api/llm-benchmark-upload：上传某一 (lang, mode) 组合的一批运行结果，上传前会做模型名归一化（normalize_model_names）并清洗易变字段（sanitize_for_commit），请求头携带Authorization: Bearer <api_key>；
• POST /api/llm-benchmark-tasks：从磁盘上的 benchmarks 目录推导任务目录，生成任务目录（task catalog）上传；
• GET /api/llm-benchmark-models?active=true：拉取网站模型注册表中 active 且 available 的模型路由（active=false或available=false的路由会被过滤掉）；
• GET /api/llm-benchmark-results?dates=true&lang=..&mode=..与?failures=true：按语言/模式/模型/日期查询历史运行日期与失败结果。

如果未设置LLM_BENCHMARK_UPLOAD_URL，ApiClient::from_env()直接返回None，整个上传链路被跳过（这是--dry-run之外的另一种本地离线方式）。

当前基准一览

basics

schema

目录结构

基准用例位于benchmarks/下，布局如下：

benchmarks/ category/ t_001_foo/ tasks/ rust.txt csharp.txt answers/ rust.rs csharp.cs spec.rs # 评分配置、reducer/schema 检查等

仓库中tools/xtask-llm-benchmark/src/benchmarks/下实际存在的分类比文档列举的两类更丰富，包括basics、schema、queries、data_modeling、auth、tables、reducers、views、lifecycle、procedures、migrations共 11 个分类、80+ 个编号任务（如t_082_hot_swap_compatibility、t_079_external_upload_flow），每个任务目录内均包含tasks/{rust,csharp,typescript}.txt提示词、answers/{rust.rs,csharp.cs,typescript.ts}金标准答案与spec.rs评分配置，部分迁移类任务还带setup/目录。TypeScript 已深度融入套件，而不仅限于文档示例中的 Rust 与 C#。

创建新基准用例

按以下 7 步新增一个基准任务：

1. 复制现有基准：复制任意已有基准文件夹，把数字前缀改成新的未使用 ID：t_123_my_task。
2. 为任务重命名：文件夹名保持ID + 短横线 slug风格，如t_123_my_task。
3. 编写任务提示词：创建/更新tasks/rust.txt和/或tasks/csharp.txt。提示词要明确（表、reducer、辅助函数、约束等），避免歧义。
4. 添加金标准答案：在answers/rust.rs和/或answers/csharp.cs中实现规范解。
5. 定义评分规则：编辑spec.rs添加 scorer（例如 schema/table/field 检查、reducer/函数是否存在检查）。
6. 快速验证：只构建金标准答案：

   cargo llm run --goldens-only --tasks t_123_my_task

7. 归类：确保文件夹位于正确的分类路径下。

评分器源码位于 eval/scorers.rs，负责对 LLM 输出做 schema/表/字段/函数存在性等结构化校验，可据此扩展spec.rs中可声明的检查类型。

常用命令

# 使用当前环境变量（providers/models 来自你的 .env）运行全部 cargo llm run # 只跑 Rust（或 C#） cargo llm run --lang rust cargo llm run --lang csharp # 只跑指定分类（使用你的实际分类名） cargo llm run --categories basics,schema # 只跑指定编号任务（全局编号） cargo llm run --tasks 0,7,12 # 显式限制 providers/models cargo llm run \ --providers openai,anthropic \ --models "openai:gpt-5 anthropic:claude-sonnet-4-5" # 干跑 cargo llm run --hash-only # 只构建上下文（不调用任何 provider） cargo llm run --goldens-only # 只构建/检查金标准答案 # 激进模式（跳过部分安全检查） cargo llm run --force # 每语言 CI 冒烟检查 cargo llm ci-check --lang rust cargo llm ci-check --lang csharp # 生成 PR 评论 markdown（对比 master 基线） cargo llm ci-comment # 使用自定义基线 ref cargo llm ci-comment --baseline-ref origin/main

输出：

• 日志输出到 stdout/stderr（遵循LLM_DEBUG/LLM_DEBUG_VERBOSE）；
• JSON 结果存放在每次运行的独立（时间戳）文件夹中，并合并进汇总报告。

5. 上下文构建（Context Construction）

基准工具会为每个任务提示词构建一份上下文（即文档），随提示词一并发送给 LLM。上下文按语言和模式而变化。

模式（Modes）

上下文构建相关代码位于 context 目录（含combine.rs、hashing.rs、paths.rs等模块），其中hashing.rs对上下文内容做哈希，--hash-only模式只产出哈希而不调用任何模型；哈希也被用作上传结果时的 mode 关联键。

Tab 过滤

为某语言构建上下文时，工具会过滤文档中的<Tabs>组件，只保留目标语言相关的内容，降低噪声、让 LLM 聚焦正确的语法。

被过滤的 tab groupId：

过滤行为：

• C# 测试：只保留value="csharp"的 tab；
• Rust 测试：只保留value="rust"的 tab；
• 如果没有任何匹配的 tab（例如client-language只有cpp/blueprint），整个 tabs 块被移除。

变换示例：

过滤前（markdown 中）：

<Tabs groupId="server-language" queryString> <TabItem value="csharp" label="C#"> C# code here </TabItem> <TabItem value="rust" label="Rust"> Rust code here </TabItem> </Tabs>

过滤后（C# 上下文）：

C# code here

文档编写最佳实践

被基准使用的文档应当遵循以下约定：

1. 使用一致的 tab groupId：服务端模块代码一律用server-language，客户端 SDK 代码一律用client-language；
2. 覆盖所有支持的语言：确保每个<Tabs>块包含你想测试的所有语言 tab；
3. 使用一致的命名约定：基准会把 LLM 输出与金标准答案做对比，因此文档应反映期望的约定（例如 C# 表名使用 PascalCase）。

6. 故障排查（Troubleshooting）

Provider 返回 HTTP 400/404

• 检查模型 ID 拼写，以及该模型在你的账号/区域是否可用；
• 对非默认网关，确认 base URL 配置正确。

超时 / 限流（Rate-limit）

• 调低LLM_BENCH_CONCURRENCY或LLM_BENCH_ROUTE_CONCURRENCY；
• 部分 provider 对突发请求限流非常激进，尽量使用带 backoff/retry 的调用路径。

结合源码可补充两点排查思路：若并发日志显示构建阶段而非请求阶段受限，可进一步调低LLM_BENCH_RUST_CONCURRENCY（默认 2）或保持LLM_BENCH_CSHARP_CONCURRENCY为 1；若上传结果报鉴权失败，请确认LLM_BENCHMARK_API_KEY与LLM_BENCHMARK_UPLOAD_URL成对出现（源码中仅设置了 URL 而未设置 key 会直接报错LLM_BENCHMARK_API_KEY required when UPLOAD_URL is set）。

7. 小结

SpacetimeDB 的cargo llm基准工具把"LLM 生成模块代码 → 构建 → 发布到本地 SpacetimeDB → 结构化评分 → 上传汇总"串成了一条可复现、可按语言/分类/任务/模型裁剪的自动化流水线。无论你是要复跑 CI 结果、为本仓库新增一个 benchmark 任务，还是接入新的模型供应商，都可以从 docs/DEVELOP.md 出发，对照 model_routes.rs、bench/utils.rs 与 benchmarks 目录逐层深入，快速定位所需改动点。

【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB