文档

2.1 基准、运行与排行榜

一次运行依次是 queued、running、scoring，最后是 completed、failed 或 cancelled；运行中可以暂停，之后再继续（失败与恢复）。

3.1 邀请里有什么

API key（Arena 的和你的模型供应商的）请放在只有你能读的文件里，不要写进代码、代码包、URL 或日志。

3.2 命令行登录

navers-arena login 会打印一个链接；在已登录的浏览器里打开它，输入终端显示的配对码并确认。命令行随后拿到一个 API key，保存在只有你能读的文件里（默认 ~/.config/navers-quant/arena-api-key）；navers-arena logout 会撤销它。也可以在 API keys 页面创建和撤销。key 只显示一次，以 Authorization: Bearer nqk_… 发送，权限按范围划分：arena:read 读取你的账号、提交、运行和排行榜，arena:submit 上传提交并开始、暂停、继续或取消你的运行。

4.1 Harness

harness 就是你的研究 agent：一个 main.py 位于顶层的 .zip 或 .tar.gz，运行开始时在一个 sandbox 作业，即这次运行的 agent 作业里，以 python main.py 启动一次。在这个作业里，agent 用 SDK 的数据客户端读取基准在 agent cutoff 之前的公开数据（每个作业能读到什么），通过平台的模型网关、在本次运行的 token 额度内调用本次运行的模型，把候选策略交给平台评估（研究评估），最后选定一个已完成的 trial。没有选定时，以 write_strategy 写出的策略为准；什么都没交的 agent 使这次运行失败。

from pathlib import Path
from navers_quant_sdk.arena import openai_client
from navers_quant_sdk.arena.agent import Research

client = openai_client()   # 指向本次作业模型网关与凭证的 openai.OpenAI 客户端
reply = client.chat.completions.create(
    model="<你为本次运行选择的模型>",
    messages=[{"role": "user", "content": "提出一个日频选股因子 ..."}],
)
# ... 把方案写进 candidate/main.py ...
research = Research()
trial = research.evaluate(Path("candidate"), key="round-1")   # 由平台评估
trial = research.wait(trial["trial_ref"])                     # 反馈，或失败报告
research.finish(trial["trial_ref"])                           # 这次运行要打分的策略

模型网关在 SDK 的重试之间保持同一个 Idempotency-Key，所以连接中断后重试的调用会拿到已记录的答复，而不是重复计费；同一个 key 配不同的请求会被拒绝。超出剩余额度的调用返回 429，budget() 显示还剩多少。工具在你自己的 agent 里执行：供应商侧工具、远程 URL 和供应商文件引用都会被拒绝，图片和文档必须内联。按你的 endpoint 的协议调用：chat、responses 或 messages（budget()["protocol"] 给出协议）；在作业使用 agent 镜像的基准上，main.py 可以用 agent_cli.run("claude_code") 把研究交给 Claude Code。完整清单见 SDK、命令行与 HTTP API。

4.2 研究评估

每个赛道设定一次运行的研究评估次数：迭代和 harness 赛道为 5 次，one-shot 没有。平台在 sandbox 中、在基准的研究窗口上评估候选策略，使用完整的评测数据和与最终评估相同的回放；agent 读不到这些数据，只拿到反馈：

• 窗口指标（比率保留 4 位小数）、按名字至多 32 个声明特征的摘要、执行、覆盖和多样性摘要（K 和合格特征数）、资格，以及剩余评估次数；
• 主组合按年的摘要及最好、最差的月份；monthly_returns、monthly_ic、quantile_groups、signal_validity、execution_issues 各节逐个读取，不占评估次数；
• 策略失败时，Python 内置异常名和你代码中的文件与行号，或拒绝结果的输出检查。不返回异常消息、打印输出和日志。

评估完成和策略失败各用一次；平台故障不用，可以再次提交同一个候选。同时只评估一个。agent 最后选定一个已完成的 trial，它的策略冻结后原样打分；没有选定时，平台循环和 Claude Code harness 选定最近一个已完成的 trial。特征值、个股和成交都不是反馈，最终窗口也不是。

4.3 你的模型

在模型页面添加你的模型：一个 endpoint 包括公网可访问的 https base URL、协议（OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages）、API key，以及在这里调用的模型名。开始 agent 运行时，你选择一个 endpoint 和它的一个模型。你的 agent 按名称调用这个模型，平台用你的 key 把每次调用转发到你的 endpoint。不带自己的 agent 时，由基准的 harness（基准为该协议提供时）驱动这个模型。

调用由你的供应商计费。平台记录每次调用的请求、响应和 token 用量，基准限制一次运行的调用次数和 token。模型页面按 endpoint 和运行列出输入、输出 token；运行页面列出它的调用。key 加密保存，只用于这些调用，不再显示（只显示最后四个字符）也不写日志，可以替换。只访问公网地址，不跟随重定向。删除被运行用过的 endpoint 时，它仍为那些运行保留。

4.4 代码包与 sandbox

代码包是一个 main.py 位于顶层的 .zip 或 .tar.gz，harness 和策略格式相同。Eval 页面可以上传代码包、复用已有提交，或打包在页面编辑器里写的 main.py。只接受普通文件和普通相对路径的目录（不允许链接、绝对路径和 ..）；被拒绝的代码包会逐条列出问题和对应路径。

代码在 Python 3.14（Linux x86-64）中运行，没有网络，也不能安装包。sandbox 预装 navers-quant-sdk、pyarrow 26.0.0、numpy 2.5.4、pandas 3.1.0、polars 2.0.0、duckdb 2.0.0、scipy 1.18.1、statsmodels 0.15.0、numba 0.68.0、scikit-learn 1.9.1、lightgbm 4.7.0、matplotlib 3.11.2、orjson 3.13.0、tqdm 4.70.1、python-dateutil、pytz 和 openai 3.37.0；本地请使用相同版本。不要把凭证放进代码包，也不要打包基准允许范围之外的行情数据（参赛条款 §5.1）。提交只保留一段时间，已在排行榜上的运行对应的提交除外。

5.1 DataSpec

类上的 data = DataSpec(...) 是必需的，只接受关键字参数：daily、quotes、trades、orders、order_queues 和 auction 接受不重复的非空字段名列表（数据集与字段）；intraday 接受一对 ("HH:MM", "HH:MM")（可带秒）、若干互不重叠的对，或 None 表示全天；history_days 取 0 到 250（默认 0）；instruments 取 None（当天股票池）或代码列表。身份列 symbol、session 和 event_time 会自动带上。

• intraday 包含起点，终点只到该秒的第 0 毫秒：("14:50", "14:56:59") 读到 14:56:59.000，("14:55", "15:00") 包含 15:00:00.000 但不含 15:00:03 的收盘快照（要读它请写 "15:00:05"）。它作用于 quotes、trades、orders 和 order_queues。
• DataSpec 写错时在导入 main.py 时就失败；基准数据里没有某个数据集或字段时在任何数据被读取之前失败。两种情况下这次运行都失败。
• 只声明需要的东西。 全市场约 3 秒一条、全字段的快照一天可达数 GB，而且评测要为窗口的每一天读一遍。

5.2 score_day 及其输出

score_day(self, today, history, date, info) 是必需的：

__init__(self, info) 是可选的，最先运行，info 的键相同；info["history"] 是作业打分那天之前的交易日。可以用它加载或训练模型。

返回值是 pyarrow.Table、pyarrow.RecordBatch 或 pandas.DataFrame，含 instrument 列（代码，每只股票最多一行）和 score 列（float64，越大越有吸引力；null 表示没有看法，否则必须有限）。只有分数的次序有意义，大小和正负都无所谓；当天股票池之外的股票行会被丢弃，没有行的股票当天没有分数。空表是合法的。返回 None、缺少列、类型不对、代码格式错误或重复、分数非有限，或超过 10 万行，都会让当天无效。

• 价格和成交量是精确十进制数。计算前请在 pyarrow 里转成 float64（pyarrow.compute.cast(column, pa.float64())）：对 decimal 列调用 to_pandas() 会得到很慢的、由 Python Decimal 组成的 object 列。

5.3 声明的特征

instrument 和 score 之外的列是声明的特征，评分中的多样性由它们算出：最多 300 个 float64 数值列，名字匹配 [A-Za-z][A-Za-z0-9_]{0,63} 且不是 session 或 score，取值有限或为 null，数值越大表示预期收益越高。每个评测日返回同一组特征；某天不同就使这次运行失败。只有真正被分数使用的独立特征组才计入，而且多样性在基准的聚类上限处饱和，所以多声明特征并不会提高它。

return pa.table({"instrument": symbols, "score": score, "momentum": momentum, "reversal": reversal})

5.4 评测日如何运行

每个评测窗口是一个 sandbox 作业，给窗口里的每一天打分，并且第 D 天的分数只用 D 之前的数据：

• 对第 D 天，作业给 P 打分：today 是 P 截至收盘的数据（含 P 的日线），history 是 P 之前的交易日，date 是 P。分数记为 D，平台从 D 起据此交易。也就是说，策略用一个收盘为止的数据给下一个交易日的股票排序。
• 作业把窗口的交易日分成连续的几段并行打分，每段在自己的隔离进程里。进程开始时调用一次 __init__（history 为它第一天之前的数据），然后按顺序对它的每一天调用 score_day。分段方式由基准固定，但崩溃的进程会重启并再次调用 __init__，所以某一天的分数应只取决于传进来的东西。需要更早的日期时，通过 history_days 从 history 取。
• 进程只能看到自己那一天的数据。进程之间、与网络和模型网关之间都不通；只有作业的 harness 读取数据服务。
• 每次 score_day 有 15 分钟。一个窗口的整个作业有每个评测日 15 分钟再加 5 分钟，最多 4 小时。
• 任何一天失败——异常、超时、崩溃或输出无效（包括声明的特征与第一个打分成功的日子不同）——都会使这次运行失败。数据服务拒绝读取的日子记为没有分数的失败日，其余日子照常进行。

5.5 一个完整的策略

import pyarrow as pa
import pyarrow.compute as pc

from navers_quant_sdk.eval import DataSpec, Policy

LEVELS = range(1, 11)
FIELDS = [f"{side}_volume_{level}" for level in LEVELS for side in ("bid", "ask")]


def depth(table: pa.Table, side: str) -> pa.Array:
    """一侧十档的挂单量；空档按 0 计。"""
    total = pa.array([0.0] * table.num_rows, pa.float64())
    for level in LEVELS:
        total = pc.add(total, pc.fill_null(pc.cast(table[f"{side}_volume_{level}"], pa.float64()), 0.0))
    return total


class OrderBookImbalance(Policy):
    data = DataSpec(quotes=FIELDS, intraday=("14:50", "14:56:59"))

    def score_day(self, today, history, date, info):
        quotes = today["quotes"]
        rows = pa.table({"symbol": quotes["symbol"], "event_time": quotes["event_time"],
                         "bid": depth(quotes, "bid"), "ask": depth(quotes, "ask")})
        # 每只股票在窗口内的最后一条快照（行不按时间排序）。
        last = (rows.sort_by([("symbol", "ascending"), ("event_time", "ascending")])
                .group_by("symbol", use_threads=False).aggregate([("bid", "last"), ("ask", "last")]))
        bid, ask = last["bid_last"], last["ask_last"]
        total = pc.add(bid, ask)
        # 空盘口不给分数（null）：不要用 0 或 NaN。
        score = pc.if_else(pc.greater(total, 0), pc.divide(pc.subtract(bid, ask), total),
                           pa.scalar(None, pa.float64()))
        return pa.table({"instrument": last["symbol"], "score": score})


POLICY = OrderBookImbalance

6.1 数据集与字段

quotes、trades、orders 和 order_queues 的行以 symbol（如 000012.SZ）、session（交易日）和 event_time（当天时刻，北京时间，毫秒精度）开头；daily 和 auction 只有 symbol 和 session。行不保证有序。价格、金额和成交量是精确十进制数（decimal128/decimal256，单位元与股），时刻是北京时间，任何字段都可能为 null：盘口某一档没有挂单时价和量可能是 0 或 null，两种都表示该档为空。

行情基础

• 交易时段（深圳）：09:15 至 09:25 开盘集合竞价，09:25 一次撮合产生开盘价；09:30 至 11:30、13:00 至 14:57 连续竞价；14:57 至 15:00 收盘集合竞价，15:00 一次撮合产生收盘价。
• 集合竞价期间的快照不是连续竞价的盘口：买一和卖一都是虚拟撮合价，第 2 档价格为 0、一侧挂着未成交余量，其余各档为空。竞价结束后的第一条快照又恢复为正常盘口（约 09:25，以及 15:00:03 前后）。盘口信号请用连续竞价期间的快照计算。
• 涨跌停。 每只股票每天的价格只能在前一收盘价上下一定幅度内变动。停牌的股票当天不交易。ST 是交易所对特别处理公司股票的标记。

6.2 公开数据

agent 在公开版本上做研究。当前的公开版本是 quotes-l10-15s-2022-2023，只有 quotes：44 个字段（四个身份字段加十档买卖价量）、289 只固定名单的深圳 A 股、2022 和 2023 两个自然年、每只股票每 15 秒最多一行（取该 15 秒内最后一条原始快照，原样保留），时段为 09:15:00 至 11:30:00 和 13:00:00 至 15:00:30。评测版本可能有全部六个数据集、所有字段、当天完整股票池、基准的交易日，以及约 3 秒一条的原始采样。

• 基于公开数据写的代码不能假设 15 秒间隔、44 个字段或每个时段都有数据。已知缺口： 2022-01-06、2022-01-10 和 2022-01-14 三天的公开快照在收盘前几分钟就结束了；评测数据也可能缺个别股票或时段。请处理缺失时段，例如退回到更早的时段，或当天不给该股票打分。
• 同样的快照以文件形式提供给你，按 CC BY-NC 4.0 发布，无需登录：从公开数据下载。运行之外不为参赛者提供数据服务。

6.3 每个作业能读到什么

数据服务在放行读取时执行 cutoff，超过的读取会被拒绝，任何作业都看不到更晚的数据。评测日本身并不隐藏：运行中每个作业的输入 eval-spec.json 都列出了它们，结果里也会出现。读不到的是它们的数据：只有评测作业和评分在评测时读取。因此 agent 里的 evaluate 只在 agent cutoff 之前的日期上运行。

7.1 公式

每个基准的窗口与权重：

正在加载当前数值…

7.2 指标

每个指标都在基准的每个窗口上分别计算，并出现在评分卡和结果文件里：

• ARR —— Top-k 现金账户的年化复利收益，含费用和手数；超额 ARR 再减去同期全市场等权基准的 ARR。
• 夏普 —— 现金账户日收益的均值除以其标准差，再乘 $\sqrt{N}$，不计无风险利率。最大回撤是该账户从历史最高点起的最大跌幅。
• RankIC —— 分数与次日收益的日度 Spearman 相关，在交易日上取平均。年化 RankICIR 是该值的均值除以其标准差，再乘 $\sqrt{N}$，公式中的 $A$ 用的就是它。
• 多空夏普 —— 每天按分数把股票分组，取最高组与最低组的次日平均收益之差；均值除以标准差，再乘 $\sqrt{N}$。它只衡量区分度，不考虑卖空限制，也不是可交易的收益。
• 换手 —— Top-k 集合中每两个交易日之间新进的比例，在交易日上取平均。
• 聚类数 K —— 声明的特征按相关性合并成簇；某一簇有合格成员且对股票分数有独立贡献时计入，多样性用 $\min(K, C) / C$。
• 用掉的 token —— agent 的模型输入加输出 token，由供应商报告、由模型网关计费。只报告，不计分。

7.3 排行榜

• 已完成的运行在有分数、满足基准的资格规则，且（对 agent）没有超出 token 额度时进入该基准的排行榜。否则评分卡会给出原因，例如 result_ineligible、score_unavailable 或 budget_exceeded。
• 每个赛道有自己的排行榜。一行是一位参赛者用一个模型（按总分）最好的一次运行，所以同一位参赛者用两个模型就有两行。模型名称按平台的模型目录统一：去掉供应商前缀和快照日期，anthropic/claude-haiku-4-5-20251001 与 claude-haiku-4-5 是同一个模型。模型名称由参赛者自报，与 v1 相同。每次完成的运行都留档；新的运行不会替换旧的，结果也不能撤回。
• 可以按总分、某个窗口的分数或汇总列排序，也可以只看一个模型；名次按所选的列计算。值相同时名次并列，按完成时间排列。缺失值显示为不可用并排在最后，而不是 0。
• 登录后，在场次中可以看到你能参加的每个基准及其排行榜。公开的排行榜展示 v1 的展示榜单，含赛道、分数和净值曲线。
• 封存的基准在主办方发布结果之前不显示排行榜。违反规则的结果，主办方可以移除（参赛条款 §3.6）。

7.4 基准设定

数据、评测日、研究额度和规则在任何评测之前就已固定，同一基准的每次运行都在相同的设定下评测：数据版本与股票池、评测日、作业上限、agent 的模型额度、评分权重和披露范围。设定改变就是新基准。

• 窗口。 在 agent 基准上，agent 在截止于 agent cutoff 的数据上研究；交出的策略随后在每个评测日被打分，每天只用更早的数据（评测日如何运行）；平台回放每日分数，并对每个窗口评分。
• 信息边界。 agent 作业只能到达截止于 agent cutoff 的数据服务和模型网关；评测作业只能到达评测数据服务，每天的 score_day 只拿到当天之前的数据。凭证按作业签发、随作业结束；你的代码从不接触平台的供应商密钥。访问受数据版本、股票、字段和时间限制，由数据服务执行，而不是由你的代码保证。平台运行策略、维护账户并计算分数。
• 模型额度。 调用经过平台的模型网关，按供应商报告的 token 数结算；结果未知的调用按全额暂记。超出额度的运行不上榜，相同的 token 额度也不代表不同模型的成本相同。调用发往你自己的模型，由你的供应商计费。

正在加载当前数值…

• 分数怎么被使用。 策略只负责给股票排序：平台自己的交易策略每天拿到排名，从最前面买入，按固定规则持有和卖出，并支付交易成本。你不控制委托、持仓或时点，只有分数的次序有意义，窗口最后一天的分数不参与交易。交易规则和成本假设随基准固定，不对外公布。
• 披露。 每个基准规定结果披露到什么程度：

8.1 结果文件

navers-arena result <run-id> --output ./result 下载评分卡和基准披露的结果文件；运行页面列出同样的文件，GET /v1/episodes/{id}/files/{path} 可以取单个文件（HTTP API）。基准从以下文件中选择：评测的 result.json（汇总统计与上面的指标）、月度与年度序列、quantile_groups.parquet（各分数组的次日收益）、signal_validity.parquet 和 execution_issues.parquet（回放的数据与执行问题）。

8.2 失败与恢复

输入错误

不合法的代码包在上传时就被拒绝，并逐条给出问题和路径。

你的代码

任何评测日的异常、超时、资源超限或输出无效，DataSpec 不合法，或者 agent 没有交出策略，都会使这次运行失败。失败的运行不会重跑。

平台错误

平台和基础设施故障会自动重试。某个作业用完重试次数时，运行会暂停而不是失败。

• 暂停的运行会在页面上说明原因。继续运行从停下的地方接着跑：已完成的作业不会重复，已记录的模型调用也不会重复计费。
• 运行进行中，你可以暂停或取消自己的运行。

8.3 局限

这套协议控制运行期间的信息访问，并把研究与最终评测分开。它不能证明模型预训练数据中不曾出现历史行情。历史评测也不能说明实盘表现或未来收益；请在基准的数据、市场时段、覆盖范围和执行假设之内理解结果。结果来自历史回测，仅供研究比较，不构成投资建议。

9.1 命令行

navers-arena login                                    # 在浏览器中确认，保存 API key
navers-arena suites                                   # 你能阅读的基准
navers-arena submit ./my_strategy --suite <基准 id> --wait
navers-arena result <run-id> --output ./result
navers-arena leaderboard <基准 id> --track <赛道> --sort window:out_of_sample

submit DIR 把目录打包成 zip（必须有 main.py；缓存、版本控制数据和链接会被跳过）并上传；带 --suite 时还会在策略基准上发起一次运行，其中的 Idempotency-Key 可以用 --idempotency-key 重复给出以安全重试。agent 基准上的运行需要选择你的一个模型，请在 Eval 页面发起；之后 status、result、jobs、logs、pause、resume 和 cancel 对它与对其他运行一样可用。--wait 跟随运行到结束，连接失败、5xx 和 429 会自动重试，只有运行完成时退出码才为 0；--timeout 限制等待时间。run SUITE SUBMISSION 用一个已有的策略提交运行一次，episodes、submissions、jobs 和 logs RUN JOB 列出你的记录、作业和可读日志。

9.2 HTTP API

站点自己的请求也走同一个 API，接口参考按服务端自己的 OpenAPI 描述（GET /v1/openapi.json）渲染：API 参考。接口里把一次运行叫作 episode，它的 id 就是 /runs/{id} 地址中的那个。读取公开基准无需登录；浏览器的写操作需要会话的 CSRF token，API key 不需要。Idempotency-Key 让创建运行可以安全重试：同一个 key 返回同一次运行，同一个 key 配不同的基准或提交会被拒绝。错误是 application/problem+json，带 code、detail 和 request_id；反馈问题时请附上 request_id。

11.1 引用

论文可在 arXiv 获取（arXiv:2610.30113）。使用 Quant Arena 时请按以下格式引用。

@misc{qian2026quantarena,
  title         = {Quant-Arena: Benchmarking LLM Agents for Quantitative Trading Research},
  author        = {Qian, Houde and Jiang, Zheng and Li, Wenyi and Xu, Chenxi and Lin, Xinjie and Peng, Yuzhao and Han, Ruoyu and Zheng, Youjie and Yang, Kaisen and Na, Qinhuai and Fu, You and Xiao, Calvin},
  year          = {2026},
  eprint        = {2610.30113},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CL},
  url           = {https://arxiv.org/abs/2610.30113},
}