FinanceGym 架构解析：面向金融智能体的五模块服务化搜索环境设计-北京尧图网络

FinanceGym 架构解析面向金融智能体的五模块服务化搜索环境设计【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research本文以 architecture.md 为主线系统拆解 FinanceGym位于finance_harness仓库如何把从原始网络语料到打分完成的完整数据流拆分为五个服务级模块corpus、index、env、graph、questions/curation/judge的衔接方式以及三条关键服务边界的契约设计。读完你可以掌握每个模块的输入输出契约、可独立扩展/替换的边界以及一条端到端构建搜索环境的可运行脚本路径。总体数据流五个模块对齐一条数据管道FinanceGym 的设计原则是每个模块只对外暴露一个小型接口下游消费该接口即可因此任何一个模块都可以被独立替换或独立扩容。官方架构图如下摘自 architecture.mdweb corpus WARCs questions.jsonl | | v v ┌──────────────┐ metadata.jsonl ┌──────────┐ │ corpus │ ───────────────► │ graph │ ─► edges.csv │ │ texts.jsonl │ │ └──────┬───────┘ └────┬─────┘ | embeddings.bin | v v ┌─────────┐ ┌───────────┐ │ index │ │ questions │ ─► questions.jsonl │ (FAISS) │ │ (v3 gen) │ └────┬────┘ └─────┬─────┘ | faiss_index.bin | v v ┌────────────────┐ ┌──────────┐ │ env │ │ curation │ ─► curated.jsonl │ (FastAPI PIT) │ └─────┬────┘ └───┬────────────┘ | | v /search, /fetch ┌─────────┐ ▲ │ judge │ ─► scores.jsonl │ agent answers └─────────┘ └───────────────────────────────┘可以把它读成两条主干语料主干WARC 原始网页 →corpus抽取嵌入 →index建 FAISS 索引 →env提供 Point-in-TimePIT搜索服务题目与评分主干graph从语料输出构建金融实体图edges.csv→questions挖掘并生成题目 →curation多阶段过滤出均衡评测集 →judge对智能体答卷打分scores.jsonl。env与题目/评分侧之间通过智能体只调用/search、/fetch两个接口形成闭环智能体回答基于它能在截止日前检索到的证据judge 按 rubric 打分。模块一financegym.corpus—— 三级并发抽取嵌入流水线corpus 模块把 web 语料 WARC 流经三个并发阶段见 extract_embed.pyReader— 单线程迭代 WARC 记录只保留rec_type response且Content-Type含html的记录把(warc_name, url, crawl_date, html)推入有界队列Extractors— 进程池默认workers cpu_count - 16对每条记录运行 trafilatura正文抽取 htmldate发布日期推断Embedders— 线程池默认 8 个 workerDEFAULT_EMBED_WORKERS 8把抽出的文章按批默认 batch 128DEFAULT_BATCH_SIZE 128发送到嵌入服务。几个值得注意的实现细节嵌入契约embed_batch通过 OpenAI 兼容的/v1/embeddings端点调用默认EMBED_URLhttp://127.0.0.1:8888/v1/embeddings、EMBED_MODELQwen/Qwen3-Embedding-4B、EMBED_DIM2560。任何会说同一 JSON 方言的后端都可以通过环境变量EMBED_URL热替换。文本上限MAX_TEXT_LEN 120_000约 40K token这是上界而非截断策略抽取结果少于MIN_TEXT_LEN 100字符的记录直接丢弃。输出格式embeddings.bin是 8 字节小端ii头n, dim由pack_header/unpack_header打包后跟 float32 数据metadata.jsonl每行一个Documentdoc_id、url、domain、pub_date、crawl_date、text_lentexts.jsonl每行{doc_id, text}。断点续跑checkpoint.txt记录已完成的 WARC 文件名重跑时跳过已完成文件embeddings.bin以rb模式从文件尾追加并在全部写完后回写真实(total, dim)头。背压与吞吐两个进程间队列容量分别调优为POOL_A_SIZE 125_000约 5 个 WARC 的 HTML 量和POOL_B_SIZE 500_000注释说明其面向 1TB 内存机器。嵌入失败批次会指数退避重试 2 次2**attempt秒3 次失败后丢弃该批。build_db子命令build_db.py则把texts.jsonl整合进corpus.dbSQLite让搜索服务器不必把全部正文常驻内存——这正是env模块能同时提供/search向量检索与/fetch全文的基础。模块二financegym.index—— FAISS 索引构建index 模块index/build.pymemory-mapembeddings.bin并构建 FAISS 索引默认索引类型ivf_sq8DEFAULT_INDEX_TYPE同时支持ivf_flat、flat_sq8、flat。从源码注释看选择ivf_sq8是为了对齐规范的 FinanceEnv 契约nlist clamp(sqrt(nvecs), 256, 65_536)由auto_nlist计算且查询时nprobe 32GPU 自动探测构建时自动检测 faiss-gpu存在时用 GPU 加速 k-means 训练否则平滑回落到 CPUsetup.md 也提示把faiss-cpu换成faiss-gpu即可启用。一个容易忽略的一致性细节nprobe 32不仅在构建时写入索引也在服务器加载时被强制设置——server.py 中ServerState.from_disk会尝试faiss.extract_index_ivf(index)并设ivf.nprobe 32对非 IVF 索引捕获RuntimeError后忽略。这保证了构建端调参与服务端调参永远一致。这些数值也被 reproducibility.md 作为可复现性 pin 值记录在案。模块三financegym.env—— Point-in-Time 搜索服务器env 是整个环境对智能体暴露的唯一入口。其核心设计在 server.py状态封装FAISS 索引、内存元数据列表、SQLite 正文连接全部封装在一个ServerStatedataclass 里工厂模式FastAPI 应用由create_app(state)工厂生成。注释说明这既让测试可以用合成状态 flat FAISS 索引 sqlite 内存连接做到完全隔离hermetic也允许单机部署多套服务API 契约小而固定POST /search、POST /fetch、GET /stats、GET /health四个端点请求/响应结构在模块内以 pydantic 模型SearchRequest、SearchHit、SearchResponse、FetchRequest、FetchResponse固化完整字段定义见 api-contract.md。搜索逻辑里有两处体现PITpoint-in-time约束的实现PIT 过滤max_date为YYYY-MM-DD字符串pub_date max_date的文档被逐条剔除过度召回设定max_date时内部检索k * 5条再过滤retrieve_k k * 5 if max_date else k避免日期过滤后结果不足 k 条。其他运行时细节索引未加载时/search返回 503SQLite 连接设置PRAGMA cache_size-4000000约 4GB 缓存与PRAGMA mmap_size85899345928GB mmap以放大 OS 页缓存/health在索引就绪前返回loading。CLI 入口支持--data-dir默认output/search/、--host、--port默认 8889。模块四financegym.graph—— 金融实体图三子命令graph 模块从 corpus 输出构建金融实体图产出edges.csv。domain_whitelist子命令是典型代表domain_whitelist.py它分三步每步都能独立重放count— 纯 Python 统计读取一个或多个metadata.jsonl快照按 domain 计数并写出domain_counts.json含total_docs、unique_domains、domain_counts三个字段。候选集默认由select_by_coverage选出——取覆盖 95%coverage0.95文档量的头部域名也可以用--top N直接截取curate— 宽口径 LLM 筛选用 Gemini 结构化输出CURATE_SYSTEM系统提示以模块级常量 pin 住批量默认 200 域名/批、16 并发判断可信的英语信息源。设计意图是宽进——宁可多留降低后续严格口径的成本cleanup— 严口径 LLM 清洗CLEANUP_SYSTEM只保留美国市场的金融从业者会真正阅读的域名100 域名/批、4 并发输出中额外记录removed_domains与前后计数的 metadata便于审计。另外两个子命令对应 extract_triples.py 与 relation_categories.py前者对白名单内文章做 Gemini 结构化三元组抽取关系分类法snake_case 动词与classify-then-extract提示词都 pin 在模块内后者把原始关系按计数 LLM 归类压缩到题目挖掘所依赖的小分类体系中。每个 pin 住的提示词常量与所在模块的对应关系见 reproducibility.md 的 Pinned prompts 表。模块五financegym.questions—— v3 题目管线v3 题目管线被拆成六个聚焦的子模块各管一段子模块职责源码锚点entity_filter共享 blocklist、垃圾模式、板块归一化、边加载器、关系归类entity_filter.pyevent_detectionbuild_indexes一次遍历 edges 产出各阶段所需全部索引与detect_event_dayssigma 阈值的天级过滤补充路径event_detection.pycutoff_selection每日得分volume × diversity × entropy、按均衡性推导每月 K、gap 约束cutoff_selection.pysituation_mining多跳路径、时间叙事、张力情境situation_mining.pygenerate按情境类型组装证据包、pin 住的QUESTION_PROMPT_TEMPLATE、垃圾实体清洗、去重generate.pyquality_judge五维裁判passes_quality_gate在代码里强制硬接受规则均值 ≥ 3.8、无维度 1、naturalness ≥ 3quality_judge.py值得注意的是build_indexes的设计对 edges 只做一次遍历就把后续每个阶段需要的 per-stage 索引全部建好而不是各阶段重复扫描——这在 edges.csv 是大文件时的开销差异是显著的。质量门方面接受规则写在代码里而不是信任 LLM 的结论字符串是这个项目贯穿始终的风格具体 pin 值见 reproducibility.md 的 Pinned gates 表。模块六financegym.curation—— 生成池到评测集的多级漏斗curation 把生成池转化为均衡评测集架构文档给出的六级漏斗及其文档化门槛各门槛函数均已核实存在于源码中Stage模块文档化门槛门槛函数Feasibilityfeasibility_audit.py4 个维度全部 ≥ 5 且 flag nonepasses_auditRelevancerelevance_filter.pyrel ≥ 5 且 naturalness ≥ 4passes_relevanceCoherencecoherence_filter.pycoherence ≥ 4passes_coherenceReclassifyreclassify_taxonomy.py发现式主题推理标签—ILP balanceilp_balance.py每轴分数上下界—Packagepackage_rubric_evidence.pyrubric ↔ 源边映射文章文本—前五级是过滤器LLM 打分代码强制阈值ILP balance 用整数线性规划在多个轴上同时满足分数上下界最后一级package_rubric_evidence做打包把 rubric 条目映射回源边pre/post evidence并附上文章文本形成题目最终的证据包——这也是 judge 侧metadata.pre_edge_evidence/post_edge_evidence字段的来源。模块七financegym.judge—— 评分与统计聚合judge 模块分两块rubric_judge.py、aggregate.pyrubric_judge— 0–4 五档0 not addressed到4 fully grounded的 Gemini 裁判系统提示JUDGE_SYSTEM以模块常量 pin 住每题逐条 rubric 构建 promptbuild_prompt。两个防御性设计值得注意_align_scores对 LLM 漏返回 rubric 项的情况做对齐修复持续失败的判分会产出占位记录——其每个 item 以judge failed: 开头由is_judge_failure(record)统一标记使下游统计可以显式剔除失败样本而不是默默接受低分。aggregate— 提供macro、bootstrap_cin1000种子 42DEFAULT_SEED/DEFAULT_N_BOOT、paired_ci按题目配对、axis_breakdown每轴用 n_boot400 控制成本、score_dist、cost_stats六类统计。judge 消费的题目字典结构question、thesis、cutoff、rubric、metadata 证据字段与逐 item 的打分输出格式完整定义在 api-contract.md 的 Judge contract 一节。三条承重服务边界架构文档最后强调了三条承重墙load-bearing边界它们决定了哪些组件可以自由替换Embedder ↔ index只要嵌入服务满足两个条件即可热替换——服务 OpenAI 兼容的/v1/embeddings端点、产出2,560 维归一化向量规范契约见 reproducibility.md。corpus 侧的embed_batch实现和EMBED_DIM环境变量就是这条契约的执行点。Env ↔ agent智能体只能看到/search、/fetch、/stats、/health四个端点永远无法直接触碰磁盘格式。这意味着智能体实现与数据布局彻底解耦——换语料、换索引类型都不影响 agent 代码。Judge ↔ aggregatorjudge 对每个 (question, agent) 对写一条评分记录聚合器消费记录中携带的 axis 标签因此新增一个评测轴只需要在题目上打标签聚合器零改动。端到端实操一条脚本构建搜索环境架构上各模块独立实操上则由 build_search_env.sh 串起语料主干的完整链路# 1) 抽取嵌入 python -m financegym.corpus.extract_embed $WARC_DIR --output $SEARCH_DIR # 2) 构建 SQLite 正文库 python -m financegym.corpus.build_db --input $SEARCH_DIR # 3) 构建 FAISS 索引 python -m financegym.index.build --input $SEARCH_DIR --index-type $INDEX_TYPE # 4) 启动搜索服务 python -m financegym.env.server --data-dir $SEARCH_DIR --host $HOST --port $PORT脚本支持的环境变量与默认值set -euo pipefail保证任一步失败即中止变量默认值说明WARC_DIRoutput/corpus/warc原始.warc.gz归档目录SEARCH_DIRoutput/searchembeddings.bin/metadata.jsonl/texts.jsonl/corpus.db/faiss_index.bin的输出目录EMBED_URL/EMBED_MODEL/EMBED_DIM见 corpus 模块嵌入服务端点、模型、维度INDEX_TYPEivf_sq8FAISS 索引类型HOST/PORT127.0.0.1/8889服务绑定地址SKIP_EMBED/SKIP_DB/SKIP_INDEX/SKIP_SERVE空任一设为真值即可跳过对应阶段分阶段可跳的设计对应着架构的核心主张每个模块有自己的输入输出契约断点续跑checkpoint、重放replay与独立扩容都建立在边界即契约之上。小结可审计性的契约化实现把架构文档与源码对照后FinanceGym 的架构可以归纳为三个层面的契约固化数据契约embeddings.bin的二进制头、metadata.jsonl/texts.jsonl的行格式、faiss_index.bin的参数nlist钳位、nprobe32全部 pin 在代码与文档中API 契约env 的四个端点以 pydantic 模型固化judge 的题目字典与逐 item 打分格式在 api-contract.md 中给出 JSON 样例提示词契约从 domain whitelist 的CURATE_SYSTEM/CLEANUP_SYSTEM到题目生成的QUESTION_PROMPT_TEMPLATE再到裁判的JUDGE_SYSTEM全部导出为模块级常量——一次 grep 就能知道契约是否被改动任何变更都视为基准变更需要提升包的小版本号见 reproducibility.md。理解这些边界之后读者可以自行决定扩展方向换嵌入后端只需满足 2,560 维归一化契约换索引只需改INDEX_TYPE扩展评测轴只需在题目上打标签——而这三件事都不需要触碰其余模块的接口。【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

FinanceGym 架构解析：面向金融智能体的五模块服务化搜索环境设计

相关推荐

Isaac Lab 入门：3 条命令装好机器人强化学习仿真环境，跑通你的第一个训练任务

Agent SLA指标体系设计与落地：从量化口径到监控闭环

RapidOCR 古籍竖排文字识别实战指南：从安装到调参一次讲清

更多资讯

SQL注入靶场实战：从报错注入到盲注的核心思路

Karukan KV cache管理全解析：llama.cpp序列上限与Beam的工程边界

软件工程术语解析：编码与设计的多层含义与实战应用

内网信息收集实战指南：网络层、主机层与服务层命令详解

Raspberry Pi Pico入门：MicroPython开发环境搭建与GPIO/PWM/串口实战

两级式光伏并网Simulink仿真要点：MPPT与逆变器双闭环全解析

今日更新

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？