FinanceGym API 契约详解FinanceGym 时点搜索服务与 Rubric 裁判接口【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-researchFinanceGym 是 google-research 仓库finance_harness模块下的金融研究基准环境它用一组固定 REST 接口把「任意 Agent」与「时点point-in-timePIT金融语料搜索环境」解耦开。本文以 api-contract.md 为骨架完整梳理POST /search、POST /fetch、GET /stats、GET /health四个端点的请求/响应契约以及裁判Judge的输入输出格式并结合 服务端源码 与 客户端实现 说明这些契约在实现层是如何被强制执行如 PIT 截止过滤、超量检索、失败占位记录的。读完本文你可以自行实现任意语言的客户端或搭建一个本地搜索环境用于跑 Agent 评测。契约总览为什么用 pydantic 模型钉死 Schema文档开篇即说明以下四个端点是任意 Agent 与 FinanceGym 搜索环境之间的公开契约且 Schema 以 pydantic 模型形式固定在financegym.env.server中这样任何语言的调用方都可以逐字段镜像出等价的数据结构。源码中确实如此SearchRequest、SearchHit、SearchResponse、FetchRequest、FetchResponse全部是BaseModel子类路由上通过response_modelSearchResponse这类声明让 FastAPI 按模型序列化响应见 create_app。这一设计意味着契约变更等同于改 pydantic 模型——服务端是唯一事实来源客户端只要按字段名对齐即可。POST /search带 PIT 截止的语义检索请求字段{ query_embedding: [0.012, ...], k: 10, max_date: 2025-06-30 }字段类型说明query_embeddingfloat 列表维度必须与索引一致标准 Qwen3-Embedding-4B 契约为 2,560 维。kint默认 10。当设置了max_date过滤时服务端内部会超量检索。max_dateYYYY-MM-DD字符串或 nullPIT 截止。pub_date max_date的文档会被排除。对照源码中的模型定义字段与默认值一一对应query_embedding: list[float]必填、k: int 10、max_date: str | None None见 SearchRequest。响应字段{ results: [ { doc_id: doc_3214, url: https://example.com/x, domain: example.com, pub_date: 2025-05-12, score: 0.873, text_preview: First 200 chars of the article ... } ], total_candidates: 50, query_time_ms: 32.4 }契约要点文档明确写出索引尚未加载完成时返回503query_time_ms只统计服务端检索耗时不含网络往返。源码层实现细节从 search() 函数 可以看到文档中每条注记的落地方式503 的触发条件state.index is None时抛出HTTPException(503, Index not loaded)若索引加载了但语料为空则返回空结果而不是报错。超量检索over-retrievalretrieve_k k * 5 if max_date else k。由于 PIT 过滤发生在 ANN 检索之后按pub_date max_date逐条丢弃先用 5 倍候选池再裁剪才能在过滤后仍尽量凑满k条且retrieve_k会被min压到文档总数以内。total_candidates的语义取值为 ANN 一次返回的候选列数indices.shape[1]即过滤前的召回宽度文档示例中 50 正对应k10时的 5 倍超量。向量归一化查询向量被 reshape 成(1, -1)并做faiss.normalize_L2与语料侧索引构建文档 所述 L2 归一化、IVF-SQ8 结构保持一致的度量空间。text_preview长度常量PREVIEW_CHARS 200即文档示例中「First 200 chars」的出处预览文本来自 SQLite 中SUBSTR(text, 1, 200)。计时口径query_time_ms从发起index.search前一刻起、到组装响应为止的本地耗时毫秒、保留两位小数确实不含网络往返。索引加载细节也值得了解ServerState.from_disk 按固定磁盘布局读取三个文件——faiss_index.bin向量索引、corpus.dbSQLite 文本库、metadata.jsonl逐文档的doc_id/url/domain/pub_date元数据对 IVF 索引还会设置nprobe 32以平衡召回率与延迟。端到端调用示例官方示例 examples/02_query_pit_search.py 演示了完整闭环先把查询字符串发给 OpenAI 兼容的嵌入服务vLLM 承载 Qwen3-Embedding-4B默认http://localhost:8888/v1/embeddings拿到 2,560 维向量后再调client.search(vec, k5, max_date2025-06-30)最后用client.fetch(hits[0][doc_id])取回全文。运行方式SEARCH_URLhttp://localhost:8889 \ EMBED_URLhttp://localhost:8888/v1/embeddings \ python examples/02_query_pit_search.py服务端启动方式见 examples/01_run_search_server.md。注意嵌入模型与维度是契约的一部分语料侧由 extract_embed.py 钉在Qwen3-Embedding-4B2,560 维查询侧若换了嵌入空间检索结果将不可解释。POST /fetch按 doc_id 取回全文请求体只有一个字段{doc_id: doc_3214}响应为{ doc_id: doc_3214, text: ...full article text..., url: https://example.com/x, domain: example.com, pub_date: 2025-05-12 }未知的 doc id 返回404。源码中对应 ServerState.fetch_doc 的一次SELECT doc_id, url, domain, pub_date, text FROM docs WHERE doc_id ?查询查不到即由路由层抛 404见 _fetch 路由。生产加载时 SQLite 会设置较激进的缓存参数PRAGMA cache_size-4000000约 4GB 缓存、PRAGMA mmap_size8589934592即 8GB 内存映射以保证/fetch的大文本读取不走磁盘随机 IO若corpus.db缺失服务端启动会打警告且/fetch返回空。GET /stats与GET /health/stats返回三个键的轻量摘要用于客户端判断环境就绪度{total_docs: 122000000, index_loaded: true, db_loaded: true}total_docs就是内存中元数据条数index_loaded/db_loaded分别反映 FAISS 索引与 SQLite 文本库是否加载成功。/health是存活探针按文档契约索引与文本库都加载完成后返回{status: ok}。从源码结构看健康路由 依据索引是否加载在ok与loading之间取值更细粒度的双组件状态请用/stats的index_loaded与db_loaded判断。FinanceGymBackend.health() 的做法值得借鉴跑评测前先同时探测/health与嵌入服务两边都应答才开工避免烧掉一整次运行。Judge 契约0–4 分制 Rubric 裁判除搜索环境外文档还钉死了裁判接口的契约——裁判消费一个问题字典和一个Agent 报告字符串。问题形状裁判依赖的可写字段{ question: Why ...?, thesis: ..., cutoff: 2025-03-31, rubric: [ {category: antecedent, criterion: ...}, {category: consequent, criterion: ...} ], metadata: { pre_edge_evidence: [{head: ..., relation: ..., tail: ..., context: ...}], post_edge_evidence: [...], source_urls_pre: [...], source_urls_post: [...] } }每个 rubric 条目产出一条裁判输出{item_idx: 0, score: 3, reasoning: ..., category: antecedent, criterion: ...}score是 0–4 的整数0 not addressed到4 fully grounded。若某条记录的所有条目reasoning都以judge failed: 开头则该记录是裁判持续失败的占位结果由is_judge_failure()识别。分数标尺与证据使用规则rubric_judge.py 的系统提示JUDGE_SYSTEM给出 0–4 的完整定义0 未涉及1 仅顺带提及2 方向正确但缺关键具体信息数字/日期/实体/机制3 有具体事实、仅小缺口4 正确、具体且可归因到可信来源。证据使用规则是契约的组成部分标[antecedent]的条目对照cutoff 前证据核验研究当时可得的数据标[consequent]的条目对照cutoff 后证据核验cutoff 之后实际发生的事。占位与重试机制源码佐证文档中「judge failed:前缀」的来龙去脉完整保留在 judge_one 中裁判以temperature0.0、JSON 响应 schemaJudgeOutput方式调用最多max_retries4次仅对瞬态错误超时、429/503/RESOURCE_EXHAUSTED做指数退避重试。重试耗尽后不抛异常而是生成全 0 分的占位列表reasoning写judge failed: 错误前 100 字符见 _placeholder_scores使下游聚合流程能继续、并能通过前缀识别失败记录。is_judge_failure 的判定条件正是文档所说scores非空且每一条reasoning都以judge failed开头。LLM 返回的条目会经 _align_scores 重新对齐到 rubric 原始顺序并补上category/criterion字段缺失的条目补 0 分并标注missing from judge output——这解释了为什么文档承诺的 per-item 输出恒与 rubric 一一对应。单问题汇总由 summarize 产出antecedent / consequent / total 各自的得分和、满分、归一化比率与 0–4 分布供 aggregate.py 做跨题聚合。提示词侧的截断常量也属契约相关参数报告正文截到 12,000 字符DEFAULT_REPORT_CHAR_LIMIT、证据三元组最多展示 30 条、来源 URL 最多 25 条、单次调用超时默认 300 秒JUDGE_CALL_TIMEOUT_S。客户端如何被契约「约束」以 FinanceGymBackend 为例financegym_backend.py 是把该契约接入 Agent 研究工具链的真实客户端它对契约的遵守方式本身就是很好的合规示范max_date是每次/search必传项backend 在构造时绑定该任务task的cutoff并在每次搜索请求中写入max_date: self.cutoff。源码注释直言丢掉这个字段会静默破坏时点合规——这正是文档把max_date设计为 PIT 强制开关的原因。URL ↔ doc_id 双向映射Agent 侧习惯按 URL 寻址FinanceGym 按doc_id寻址。backend 维护一个每任务的url → doc_id表语料中缺 URL、或两条文档共用一个 URL 时改用合成句柄financegym://doc_id保证映射 1:1避免visit读错文章。白名单式抓取fetch 只接受「本 backend 曾经从/search返回过的 URL」否则直接返回错误而绝不回落到开放网络——这一条规则保证了基准运行期间 Agent 永远只能看到 cutoff 前的语料。结果整形搜索命中的domain与pub_date拼成标题如example.com — 2025-05-12text_preview作为 snippet 呈现给 Agent。关键文件索引内容路径本文档公开契约api-contract.md服务端实现四个端点 pydantic 模型server.py裁判实现0–4 分制、重试与占位rubric_judge.py客户端 PIT 后端financegym_backend.py查询示例02_query_pit_search.py服务器启动说明01_run_search_server.md复现性约定嵌入模型/维度reproducibility.md适用前提小结/search的嵌入向量必须与索引同空间标准契约为 Qwen3-Embedding-4B、2,560 维、L2 归一化max_date用YYYY-MM-DD字符串服务端按字典序与pub_date比较做过滤评测环境要求搜索服务默认端口 8889与嵌入服务默认端口 8888均已就绪否则用/health与/stats先探活。【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
FinanceGym API 契约详解FinanceGym 时点搜索服务与 Rubric 裁判接口【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-researchFinanceGym 是 google-research 仓库finance_harness模块下的金融研究基准环境它用一组固定 REST 接口把「任意 Agent」与「时点point-in-timePIT金融语料搜索环境」解耦开。本文以 api-contract.md 为骨架完整梳理POST /search、POST /fetch、GET /stats、GET /health四个端点的请求/响应契约以及裁判Judge的输入输出格式并结合 服务端源码 与 客户端实现 说明这些契约在实现层是如何被强制执行如 PIT 截止过滤、超量检索、失败占位记录的。读完本文你可以自行实现任意语言的客户端或搭建一个本地搜索环境用于跑 Agent 评测。契约总览为什么用 pydantic 模型钉死 Schema文档开篇即说明以下四个端点是任意 Agent 与 FinanceGym 搜索环境之间的公开契约且 Schema 以 pydantic 模型形式固定在financegym.env.server中这样任何语言的调用方都可以逐字段镜像出等价的数据结构。源码中确实如此SearchRequest、SearchHit、SearchResponse、FetchRequest、FetchResponse全部是BaseModel子类路由上通过response_modelSearchResponse这类声明让 FastAPI 按模型序列化响应见 create_app。这一设计意味着契约变更等同于改 pydantic 模型——服务端是唯一事实来源客户端只要按字段名对齐即可。POST /search带 PIT 截止的语义检索请求字段{ query_embedding: [0.012, ...], k: 10, max_date: 2025-06-30 }字段类型说明query_embeddingfloat 列表维度必须与索引一致标准 Qwen3-Embedding-4B 契约为 2,560 维。kint默认 10。当设置了max_date过滤时服务端内部会超量检索。max_dateYYYY-MM-DD字符串或 nullPIT 截止。pub_date max_date的文档会被排除。对照源码中的模型定义字段与默认值一一对应query_embedding: list[float]必填、k: int 10、max_date: str | None None见 SearchRequest。响应字段{ results: [ { doc_id: doc_3214, url: https://example.com/x, domain: example.com, pub_date: 2025-05-12, score: 0.873, text_preview: First 200 chars of the article ... } ], total_candidates: 50, query_time_ms: 32.4 }契约要点文档明确写出索引尚未加载完成时返回503query_time_ms只统计服务端检索耗时不含网络往返。源码层实现细节从 search() 函数 可以看到文档中每条注记的落地方式503 的触发条件state.index is None时抛出HTTPException(503, Index not loaded)若索引加载了但语料为空则返回空结果而不是报错。超量检索over-retrievalretrieve_k k * 5 if max_date else k。由于 PIT 过滤发生在 ANN 检索之后按pub_date max_date逐条丢弃先用 5 倍候选池再裁剪才能在过滤后仍尽量凑满k条且retrieve_k会被min压到文档总数以内。total_candidates的语义取值为 ANN 一次返回的候选列数indices.shape[1]即过滤前的召回宽度文档示例中 50 正对应k10时的 5 倍超量。向量归一化查询向量被 reshape 成(1, -1)并做faiss.normalize_L2与语料侧索引构建文档 所述 L2 归一化、IVF-SQ8 结构保持一致的度量空间。text_preview长度常量PREVIEW_CHARS 200即文档示例中「First 200 chars」的出处预览文本来自 SQLite 中SUBSTR(text, 1, 200)。计时口径query_time_ms从发起index.search前一刻起、到组装响应为止的本地耗时毫秒、保留两位小数确实不含网络往返。索引加载细节也值得了解ServerState.from_disk 按固定磁盘布局读取三个文件——faiss_index.bin向量索引、corpus.dbSQLite 文本库、metadata.jsonl逐文档的doc_id/url/domain/pub_date元数据对 IVF 索引还会设置nprobe 32以平衡召回率与延迟。端到端调用示例官方示例 examples/02_query_pit_search.py 演示了完整闭环先把查询字符串发给 OpenAI 兼容的嵌入服务vLLM 承载 Qwen3-Embedding-4B默认http://localhost:8888/v1/embeddings拿到 2,560 维向量后再调client.search(vec, k5, max_date2025-06-30)最后用client.fetch(hits[0][doc_id])取回全文。运行方式SEARCH_URLhttp://localhost:8889 \ EMBED_URLhttp://localhost:8888/v1/embeddings \ python examples/02_query_pit_search.py服务端启动方式见 examples/01_run_search_server.md。注意嵌入模型与维度是契约的一部分语料侧由 extract_embed.py 钉在Qwen3-Embedding-4B2,560 维查询侧若换了嵌入空间检索结果将不可解释。POST /fetch按 doc_id 取回全文请求体只有一个字段{doc_id: doc_3214}响应为{ doc_id: doc_3214, text: ...full article text..., url: https://example.com/x, domain: example.com, pub_date: 2025-05-12 }未知的 doc id 返回404。源码中对应 ServerState.fetch_doc 的一次SELECT doc_id, url, domain, pub_date, text FROM docs WHERE doc_id ?查询查不到即由路由层抛 404见 _fetch 路由。生产加载时 SQLite 会设置较激进的缓存参数PRAGMA cache_size-4000000约 4GB 缓存、PRAGMA mmap_size8589934592即 8GB 内存映射以保证/fetch的大文本读取不走磁盘随机 IO若corpus.db缺失服务端启动会打警告且/fetch返回空。GET /stats与GET /health/stats返回三个键的轻量摘要用于客户端判断环境就绪度{total_docs: 122000000, index_loaded: true, db_loaded: true}total_docs就是内存中元数据条数index_loaded/db_loaded分别反映 FAISS 索引与 SQLite 文本库是否加载成功。/health是存活探针按文档契约索引与文本库都加载完成后返回{status: ok}。从源码结构看健康路由 依据索引是否加载在ok与loading之间取值更细粒度的双组件状态请用/stats的index_loaded与db_loaded判断。FinanceGymBackend.health() 的做法值得借鉴跑评测前先同时探测/health与嵌入服务两边都应答才开工避免烧掉一整次运行。Judge 契约0–4 分制 Rubric 裁判除搜索环境外文档还钉死了裁判接口的契约——裁判消费一个问题字典和一个Agent 报告字符串。问题形状裁判依赖的可写字段{ question: Why ...?, thesis: ..., cutoff: 2025-03-31, rubric: [ {category: antecedent, criterion: ...}, {category: consequent, criterion: ...} ], metadata: { pre_edge_evidence: [{head: ..., relation: ..., tail: ..., context: ...}], post_edge_evidence: [...], source_urls_pre: [...], source_urls_post: [...] } }每个 rubric 条目产出一条裁判输出{item_idx: 0, score: 3, reasoning: ..., category: antecedent, criterion: ...}score是 0–4 的整数0 not addressed到4 fully grounded。若某条记录的所有条目reasoning都以judge failed: 开头则该记录是裁判持续失败的占位结果由is_judge_failure()识别。分数标尺与证据使用规则rubric_judge.py 的系统提示JUDGE_SYSTEM给出 0–4 的完整定义0 未涉及1 仅顺带提及2 方向正确但缺关键具体信息数字/日期/实体/机制3 有具体事实、仅小缺口4 正确、具体且可归因到可信来源。证据使用规则是契约的组成部分标[antecedent]的条目对照cutoff 前证据核验研究当时可得的数据标[consequent]的条目对照cutoff 后证据核验cutoff 之后实际发生的事。占位与重试机制源码佐证文档中「judge failed:前缀」的来龙去脉完整保留在 judge_one 中裁判以temperature0.0、JSON 响应 schemaJudgeOutput方式调用最多max_retries4次仅对瞬态错误超时、429/503/RESOURCE_EXHAUSTED做指数退避重试。重试耗尽后不抛异常而是生成全 0 分的占位列表reasoning写judge failed: 错误前 100 字符见 _placeholder_scores使下游聚合流程能继续、并能通过前缀识别失败记录。is_judge_failure 的判定条件正是文档所说scores非空且每一条reasoning都以judge failed开头。LLM 返回的条目会经 _align_scores 重新对齐到 rubric 原始顺序并补上category/criterion字段缺失的条目补 0 分并标注missing from judge output——这解释了为什么文档承诺的 per-item 输出恒与 rubric 一一对应。单问题汇总由 summarize 产出antecedent / consequent / total 各自的得分和、满分、归一化比率与 0–4 分布供 aggregate.py 做跨题聚合。提示词侧的截断常量也属契约相关参数报告正文截到 12,000 字符DEFAULT_REPORT_CHAR_LIMIT、证据三元组最多展示 30 条、来源 URL 最多 25 条、单次调用超时默认 300 秒JUDGE_CALL_TIMEOUT_S。客户端如何被契约「约束」以 FinanceGymBackend 为例financegym_backend.py 是把该契约接入 Agent 研究工具链的真实客户端它对契约的遵守方式本身就是很好的合规示范max_date是每次/search必传项backend 在构造时绑定该任务task的cutoff并在每次搜索请求中写入max_date: self.cutoff。源码注释直言丢掉这个字段会静默破坏时点合规——这正是文档把max_date设计为 PIT 强制开关的原因。URL ↔ doc_id 双向映射Agent 侧习惯按 URL 寻址FinanceGym 按doc_id寻址。backend 维护一个每任务的url → doc_id表语料中缺 URL、或两条文档共用一个 URL 时改用合成句柄financegym://doc_id保证映射 1:1避免visit读错文章。白名单式抓取fetch 只接受「本 backend 曾经从/search返回过的 URL」否则直接返回错误而绝不回落到开放网络——这一条规则保证了基准运行期间 Agent 永远只能看到 cutoff 前的语料。结果整形搜索命中的domain与pub_date拼成标题如example.com — 2025-05-12text_preview作为 snippet 呈现给 Agent。关键文件索引内容路径本文档公开契约api-contract.md服务端实现四个端点 pydantic 模型server.py裁判实现0–4 分制、重试与占位rubric_judge.py客户端 PIT 后端financegym_backend.py查询示例02_query_pit_search.py服务器启动说明01_run_search_server.md复现性约定嵌入模型/维度reproducibility.md适用前提小结/search的嵌入向量必须与索引同空间标准契约为 Qwen3-Embedding-4B、2,560 维、L2 归一化max_date用YYYY-MM-DD字符串服务端按字典序与pub_date比较做过滤评测环境要求搜索服务默认端口 8889与嵌入服务默认端口 8888均已就绪否则用/health与/stats先探活。【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
