第 4 章 · 06 配置:环境变量与密钥

第 4 章 · 06 配置:环境变量与密钥

本节摘要:Vibe-Trading 把密钥和部署相关的选择放在环境变量或本地 Settings 里,而不是源码中——这是基本的安全实践。本节讲清配置的三个核心主题:一是环境文件(.env),管理模型厂商、模型名、数据源 token、超时等;二是密钥与数据源的关系,很多工作流无需付费 key,但 A 股基本面富化和某些专属工作流需要对应凭证;三是模型选择对工具调用质量的影响,长研究、swarm、多步回测要优先选工具调用能力强的模型,避免用小蒸馏模型。最后讲非本地部署的 API_AUTH_KEY 与 Bearer 鉴权。读完本节,你能正确配置环境,并理解为什么「模型选择」不只是性能问题,而是研究质量的关键。

内容来源:英文文档 getting-started/configuration 汉化,补充第 1 章样章已提到的配置要点。

学习目标

阅读完本节,你应当能够:

1. 写出一个最小可用的 .env 配置(厂商、模型、token、超时)。
2. 理解密钥与数据源的关系——哪些工作流需要付费 key,哪些不需要。
3. 用 vibe-trading init 交互式完成本地配置。
4. 解释模型选择对工具调用质量的影响,知道为什么长研究要避免小蒸馏模型。
5. 配置非本地部署的鉴权(API_AUTH_KEY + Bearer)。
6. 区分本地配置与源码,理解为什么密钥不能进源码。

一、配置哲学:密钥不进源码

Vibe-Trading 的配置遵循一个基本原则:

密钥和部署相关的选择,放在环境变量或本地 Settings 里,不放在源码中。

这样做有三个原因:

1. 安全:源码可能被分享、上传到 Git,密钥一旦泄露后果严重(尤其券商 token)。
2. 可移植:不同环境(开发机、服务器)用不同配置,不必改源码。
3. 可回滚:换配置不影响代码逻辑,出问题易于排查。

所以你的本地会有一个环境文件(通常是 .env),记录所有敏感或环境相关的配置项。源码里只读这些变量,不硬编码。

💡 .env 不要进 Git:如果你 fork 了项目做二次开发,务必把 .env 加到 .gitignore,避免 accidentally 提交密钥。

二、环境文件:.env

一个典型的 .env 文件长这样:

# 模型厂商与模型名
LANGCHAIN_PROVIDER=deepseek
LANGCHAIN_MODEL_NAME=deepseek-v4-pro

# 数据源 token(按需)
TUSHARE_TOKEN=your-token

# 长研究的超时
TIMEOUT_SECONDS=2400
​

关键字段含义:

💡 vibe-trading init 帮你生成:不必手写 .env,运行 vibe-trading init 会以交互方式引导你完成所有配置,自动生成 .env。

三、密钥与数据源的关系:很多工作流不需要付费 key

一个常见的误解是「不付费就用不了 Vibe-Trading」。其实很多工作流在没有付费行情 key 时也能跑:

不需要付费 key 的工作流:

• 港股、美股行情(yfinance、AKShare 公开数据)。
• 加密货币(OKX、CCXT 公开行情)。
• 文档读取与分析。
• 交易日志分析(Shadow Account)。
• 静态分析(读已有的策略代码、报告)。

需要对应凭证的工作流:

• A 股基本面富化:ROE、市盈率、营收等财务字段,需要 TUSHARE_TOKEN。
• 部分厂商专属工作流:某些数据源或工具链需要特定凭证。
• 某些专业行情:Futu 等需要开户。

💡 入门不必付费:第一次跑通研究,用 yfinance + OKX 公开数据即可,零成本。等你需要 A 股基本面富化时,再申请 Tushare token。

四、模型选择:工具调用质量是关键

配置里最影响研究质量的不是数据源,而是模型选择。原因是 Vibe-Trading 的核心是一个 agent loop——模型根据你的提示,决定调用哪些工具、按什么顺序调用。如果模型工具调用能力弱,整个研究流程就会出错或低效。

选模型的几条原则:

1. 长研究、swarm、多步回测:优先选工具调用能力强的模型。这些场景需要模型反复、准确地调用工具,弱模型会调错工具或漏调。
2. 避免小蒸馏模型用于「编造答案代价高」的工作流:在金融研究里,编造一个错误的回测结果比承认「我不知道」危险得多。小蒸馏模型倾向于「自信地胡说」,在严肃研究里不可接受。
3. 平衡成本与质量:日常快速试跑可以用较便宜的模型;严肃研究、要交付的结果用更强的模型。

⚠️ 金融研究的特殊性:在聊天场景里,模型胡说一句「巴黎是英国首都」顶多闹个笑话;但在金融研究里,模型胡说「这个策略年化 20%」可能导致你做出错误决策。所以模型选择宁可偏强,不要图便宜用不可靠的模型。本教程所有配置建议均不构成投资建议。

五、非本地部署:API_AUTH_KEY 与 Bearer 鉴权

如果你只在本机用 CLI 或 Web UI,不需要关心这一节。但如果你做非本地部署(比如把 Vibe-Trading 部署成 API 服务或公网 Web 应用),就必须配置鉴权:

# 在 .env 里配置 API 鉴权密钥
API_AUTH_KEY=your-secret-api-key
​

部署后,所有请求必须带上这个 key 才能访问:

Authorization: Bearer <your-secret-api-key>
​

这层鉴权的目的是防止未授权访问——公网部署如果不加鉴权,任何人都能调用你的 Vibe-Trading 实例(消耗你的模型额度、读取你的数据、甚至触发账户操作)。

⚠️ 公网部署必须鉴权:API_AUTH_KEY 不是可选项,是安全底线。如果你把 Vibe-Trading 暴露到公网却不加鉴权,等于把你的模型额度、数据、甚至账户操作权限开放给所有人。

六、配置的最佳实践

汇总几条配置的最佳实践:

1. 用 vibe-trading init 起步:不要手写 .env,用 init 交互完成,避免字段写错。
2. .env 不进 Git:加到 .gitignore,防止 accidentally 提交密钥。
3. 入门零成本:先用公开数据源(yfinance/OKX)跑通,再按需加 token。
4. 模型选强的:严肃研究用工具调用能力强的模型,避免小蒸馏模型。
5. 公网必鉴权:非本地部署务必配 API_AUTH_KEY + Bearer。
6. 超时调够:TIMEOUT_SECONDS 对长研究(多步回测、swarm)要调大,避免中途超时。
7. 密钥分级:数据源 token(如 TUSHARE_TOKEN)和 API 鉴权 key(如 API_AUTH_KEY)分开管理,不要混用。

七、配置与五步工作流的关系

把配置放回第 2 章 01 的五步工作流:

Plan    → 模型决定调哪些工具(受 LANGCHAIN_MODEL_NAME 影响)
Ground  → 拉数据(受 TUSHARE_TOKEN 等数据源 token 影响)
Execute → 跑回测/分析(受 TIMEOUT_SECONDS 影响)
Validate→ 验证(模型质量影响验证逻辑的准确性)
Deliver → 交付(公网部署受 API_AUTH_KEY 影响)
​

你会发现配置几乎影响每一步——模型质量决定 Plan/Execute 的准确度,数据源 token 决定 Ground 能拉什么数据,超时决定长任务能不能跑完,鉴权决定能否安全交付。所以配置不是「装好就行」的附属品,而是研究质量的基础设施。

本节要点回顾

1. 配置哲学:密钥与部署选择放环境变量/Settings,不进源码;.env 不进 Git。
2. 环境文件:LANGCHAIN_PROVIDER、LANGCHAIN_MODEL_NAME、TUSHARE_TOKEN、TIMEOUT_SECONDS。
3. vibe-trading init:交互式生成 .env,不必手写。
4. 密钥与数据源:港股/美股/加密/文档/日志/静态分析无需付费 key;A 股基本面需 TUSHARE_TOKEN。
5. 模型选择:长研究/swarm/多步回测优先选工具调用强的模型;避免小蒸馏模型用于「编造代价高」的工作流。
6. 公网鉴权:非本地部署必须配 API_AUTH_KEY,请求带 Authorization: Bearer <key>。
7. 配置影响每一步:模型质量、数据 token、超时、鉴权分别影响 Plan/Ground/Execute/Deliver。

⚠️ 本节所有配置建议均不构成投资建议。模型输出的研究结果可能出错,实盘前必须经过你自己的判断、券商确认、模拟盘验证和风险控制。

至此第 4 章 P0 批次的三节(Shadow Account、命令行参考、配置)完成。第 4 章其余 P1/P2 内容(多智能体团队 swarm、金融技能库、MCP 服务、Cloudflare Pages 部署)留待后续批次推进。读完 P0 批次的全部内容,你已经能跑通研究闭环、看懂回测、连上数据、安全地碰账户,并用进阶工具把研究做深。