4. 环境与工具准备

在金融智能体项目中，环境与工具准备不是简单的“装包”环节，而是决定后续研究能否复现、能否扩展、能否稳定运行的基础工程。本节围绕五个核心对象展开：Python生态、金融数据API、向量数据库、LLM接口与项目脚手架。它们共同构成智能体从数据获取、知识存储、推理调用到工程组织的完整底座。

核心原理：五层工具栈的协作关系

金融智能体的运行链路可以抽象为“数据输入—知识增强—模型推理—工程编排”四段。Python生态负责统一运行时与依赖管理；金融数据API提供行情、财报、宏观等结构化数据；向量数据库把非结构化文本转为可检索的语义索引；LLM接口承担理解、生成与工具调用；项目脚手架则把配置、密钥、日志、测试与模块边界固定下来。五者不是并列关系，而是存在明确的依赖方向：脚手架承载配置，配置驱动API与数据库连接，连接结果进入LLM上下文，最终由Python代码统一调度。

方法流程：从零搭建可运行环境

建议按以下顺序推进，避免依赖冲突与密钥泄露。第一步，创建独立虚拟环境并锁定Python版本。第二步，安装核心依赖并生成依赖清单。第三步，配置金融数据API的访问凭证。第四步，启动向量数据库并完成集合初始化。第五步，封装LLM接口并做连通性测试。第六步，用脚手架组织目录与配置。

# 1. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 2. 安装核心依赖
pip install akshare tushare pandas numpy chromadb  python-dotenv loguru pytest

# 3. 生成依赖清单
pip freeze > requirements.txt

# 4. 配置环境变量（.env）
FIN_DATA_=your_tushare_
LLM_=your_llm_key
LLM_BASE_URL=https://api..com/v1
VECTOR_DB_PATH=./data/chroma

脚手架目录建议采用“配置与代码分离、数据与逻辑分离”的原则。一个可直接复用的最小结构如下：

fin_agent/
├── config/
│   └── settings.py
├── src/
│   ├── data/
│   │   └── market_api.py
│   ├── rag/
│   │   └── vector_store.py
│   ├── llm/
│   │   └── client.py
│   └── agent/
│       └── orchestrator.py
├── tests/
│   └── test_connectivity.py
├── .env
└── requirements.txt

案例/场景：一次完整的连通性验证

假设我们要验证“获取某只股票近5日行情，写入向量库，并让LLM基于检索结果生成一句话摘要”。首先调用金融数据API拉取数据，其次把行情摘要文本向量化后写入Chroma集合，然后通过LLM接口发起一次带上下文的问答。若三步均返回预期结果，说明工具栈已打通。关键检查点包括：API是否返回非空DataFrame、向量库是否成功写入并可按相似度检索、LLM是否在超时时间内返回结构化响应。

误区/复盘：常见准备阶段的坑

• 依赖版本冲突：不同库对numpy或pydantic版本要求不一致，导致导入即报错。应使用虚拟环境并固定版本。
• 密钥硬编码：把写进代码并提交到仓库，造成泄露。必须使用.env与.gitignore。
• 向量维度不匹配：嵌入模型输出768维，集合却按1536维创建，写入时报错。创建集合前先确认模型维度。
• 忽略超时与重试：LLM接口偶发超时导致整个智能体链路中断。应设置超时、重试与降级策略。
• 目录随意堆放：数据、模型、日志混在一起，后期无法复现实验。脚手架应提前规划模块边界。