在 Windows 系统部署对冲基金分析工具 ai-hedge-fund 的笔记

#工作记录

一、环境准备

在部署对冲基金分析工具ai-hedge-fund前，需提前安装好必备软件，为后续工作搭建好基础环境。

1. 安装 Anaconda

Anaconda 集成了 Python 及众多科学计算库，是项目运行的重要基础。从Anaconda 官方网站下载适合 Windows 系统的安装包，下载完成后，双击安装包，按照安装向导的提示进行操作，注意在安装过程中可选择将 Anaconda 添加到系统环境变量，方便后续使用。安装完成后，打开 Anaconda Prompt，可通过输入conda --version命令来验证是否安装成功。

conda --version

2. 安装 Poetry

Poetry 用于项目的依赖管理和环境配置。在 Anaconda Prompt 中执行pip install poetry命令进行安装。安装成功后，输入poetry --version，若显示出版本信息，则说明安装成功。Poetry 安装路径通常为D:\ProgramData\anaconda3\Scripts\poetry.exe，在后续配置 PyCharm 时会用到此路径。

pip install poetry

poetry --version

 【笔记】快速安装Poetry-CSDN博客

 poetry 的路径：

D:\ProgramData\anaconda3\Scripts\poetry.exe 

3. 安装 Node.js 和 npm

Node.js 和 npm 是前端项目运行的必要环境。从Node.js 官方网站下载 Windows 版本的安装包，安装过程中保持默认设置即可。安装完成后，打开命令提示符或 PowerShell，分别输入node -v和npm -v，若能显示出版本号，表明安装成功。

node -v

npm -v

4. 安装 GitHub Desktop

GitHub Desktop 方便我们进行代码的克隆与管理。

从GitHub Desktop 官方网站下载安装包，安装完成后，打开软件并登录自己的 GitHub 账号。

5. 安装 Ollama

Ollama 用于本地大语言模型推理。从Ollama 官方网站下载 Windows 版本的安装包，安装完成后，在命令提示符中执行ollama serve启动服务。

若提示Error: listen tcp 127.0.0.1:11434: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.，表示端口 11434 被占用，可通过以下方法解决：

• 查找占用端口的进程：在命令提示符或 PowerShell 中执行netstat -ano | findstr :11434，找到对应进程 ID（PID）。

• 终止进程：执行taskkill /F /PID [PID] （将[PID]替换为实际进程 ID） 。

• 更换端口：执行ollama serve --port 12345 （将12345替换为其他未被占用端口），同时需在后续使用中修改代码中 Ollama API 地址 。

二、克隆项目

使用 GitHub Desktop 克隆项目代码到本地，方便后续进行项目的部署与调试。

1. 打开 GitHub Desktop，点击File -> Clone repository。
2. 在弹出窗口的URL选项卡中，输入项目 GitHub 地址https://github.com/virattt/ai-hedge-fund.git。
3. 选择本地存储路径，点击Clone按钮开始克隆项目。
4. 克隆完成后，进入项目文件夹，空白处右键用PyCharm打开，后续的依赖安装、命令执行等操作都可在PyCharm中进行。

三、在 PyCharm 中配置 Poetry 解释器

【笔记】PyCharm 中创建Poetry解释器-CSDN博客

PyCharm 是常用的 Python 开发集成环境，正确配置 Poetry 解释器有助于项目的开发与运行。

1. 打开 PyCharm，新建项目或打开已克隆的ai-hedge-fund项目。
2. 依次点击File -> Settings（Windows/Linux）或PyCharm -> Preferences（Mac）。
3. 在弹出的窗口中，选择Project: [项目名称] -> Python Interpreter。
4. 点击右上角的齿轮图标，选择Add。
5. 在弹出的窗口中，选择Poetry Environment，确保Use existing environment被选中，点击...按钮，在文件浏览窗口中找到并选择D:\ProgramData\anaconda3\Scripts\poetry.exe。
6. 点击OK保存配置，完成 Poetry 解释器的配置。

四、配置环境变量

环境变量的配置是为项目提供必要的 API 密钥等信息，确保项目能够正常运行。

1. 创建.env 文件

在项目根目录下，打开命令提示符或 PowerShell，执行copy .env.example .env命令，复制.env.example文件为.env文件。

cp .env.example .env

2. 编辑.env 文件

使用文本编辑器（如 Notepad++、VS Code 等）打开.env文件，添加以下 API 密钥：

# For running LLMs hosted by openai (gpt-4o, gpt-4o-mini, etc.)
# Get your OpenAI API key from https://platform.openai.com/
OPENAI_API_KEY=your-openai-api-key

# For running LLMs hosted by groq (deepseek, llama3, etc.)
# Get your Groq API key from https://groq.com/
GROQ_API_KEY=your-groq-api-key

# For getting financial data to power the hedge fund
# Get your Financial Datasets API key from https://financialdatasets.ai/
FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

  API 密钥获取（有限的免费额度，完整功能API密钥可能要收费）

openai-api-key获取网址：

https://platform.openai.com/welcome?step=try

groq-api-key获取网址：

https://console.groq.com/home

financial-datasets-api-key获取网址：

Financial Datasets | Stock Market API

五、安装项目依赖

项目依赖的安装是确保项目各功能模块正常运行的关键步骤，需分别安装根项目依赖、后端应用依赖和前端应用依赖。

安装根项目依赖

在项目根目录的终端中，执行poetry install命令，Poetry 会根据项目的pyproject.toml文件自动安装所需的依赖包。

poetry install

六、运行项目

完成上述步骤后，即可运行项目进行对冲基金分析。

• 1、在项目根目录的终端中，执行poetry run python src/main.py --ticker AAPL --ollama命令（其中--ticker AAPL可根据需求修改为其他股票代码，--ollama表示使用 Ollama 进行本地 LLM 推理）。

poetry run python src/main.py --ticker AAPL --ollama
​

• 2、执行命令后，会提示选择 AI 分析师，通过按↑ ↓箭头移动光标，按空格键选择分析师，按回车键确认选择。

• 3、接着会提示选择 Ollama 模型，通过按↑ ↓箭头移动光标，按回车键确认选择。

• 常见问题及解决：
• • LLM 调用失败（状态码 502 等）：

【笔记】排查并解决Error in LLM call after 3 attempts: (status code: 502)-CSDN博客

• • • 尝试使用更小的模型，如gemma3:4b、llama3:7b 。

• • • 修改src/tools/llm.py增加超时时间和重试次数，并在重试时尝试重启 Ollama 服务 。具体可在call_ollama函数中增加相关逻辑，例如：

def call_ollama(prompt, model="gemma3:4b", max_retries=10, timeout=300):​
    url = "http://localhost:11434/api/generate"​
    payload = {​
        "model": model,​
        "prompt": prompt,​
        "stream": False,​
        "temperature": 0.1,​
        "max_tokens": 1500,​
        "top_p": 0.9,​
        "frequency_penalty": 0.2​
    }​
    ​
    for attempt in range(max_retries):​
        try:​
            logger.info(f"LLM call attempt {attempt+1}/{max_retries}")​
            response = requests.post(url, json=payload, timeout=timeout)​
            response.raise_for_status()​
            return response.json()["response"]​
        except Exception as e:​
            logger.warning(f"LLM call failed: {e}")​
            # 每3次重试重启一次服务​
            if attempt % 3 == 0: ​
                try:​
                    subprocess.run(["taskkill", "/F", "/IM", "ollama.exe"], check=True)​
                    time.sleep(2)​
                    subprocess.Popen(["ollama", "serve"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)​
                    time.sleep(5) ​
                except Exception as restart_e:​
                    logger.warning(f"Failed to restart Ollama: {restart_e}")​
            time.sleep(5 * (attempt + 1)) ​
    ​
    raise Exception("Failed to get response from LLM after multiple attempts")

• 优化 Ollama 配置，在~/.ollama/config.toml中设置cache_size、threads等参数 。例如：

[models]​
cache_size = 8  # 减少缓存大小，单位为 GB​
threads = 4     # 减少线程数，根据 CPU 核心数调整​
​
[server]​
timeout = 300   # 增加超时时间，避免请求过早失败

• OpenAI API 配额不足（错误代码 429）：

• • 检查 OpenAI 账户配额，升级付费计划或切换到本地 Ollama 模型 。

• 金融数据 API 请求被限流（错误代码 429）：

• • 在src/tools/api.py中添加指数退避重试机制，避免频繁请求 。例如：

import time
import requests
from requests.exceptions import RequestException

def search_line_items(ticker, items, api_key=None):
    url = f"https://financialdatasets.ai/api/financials/{ticker}"
    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
    params = {"items": ",".join(items)}
    
    max_retries = 5
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, params=params, timeout=30)
            response.raise_for_status()
            return response.json()
        except RequestException as e:
            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
                print(f"Rate limited. Retrying in {retry_after} seconds...")
                time.sleep(retry_after)
                continue
            raise Exception(f"Error fetching data: {ticker} - {response.status_code} - {response.text}")
    
    raise Exception(f"Failed after {max_retries} attempts: {ticker}")

• 减少并发请求，一次只分析一只股票并减少启用的分析师数量 。

运行成功后，可在终端查看各分析师对股票的评估、交易决策及投资组合总结等分析结果。

七、注意事项

1. 密钥准确性：确保.env文件中的 API 密钥正确，否则项目可能无法正常获取数据或调用模型。
2. 网络连接：运行项目时需保证网络正常，因为部分数据需从网络获取。
3. 权限问题：确保对项目文件夹有足够的读写权限，避免因权限不足导致项目运行出错。
4. 免责声明：该项目仅作教育和研究用途，不可用于实际交易或投资，不提供投资建议，使用前务必咨询财务顾问。
5. 代理设置：确保在运行程序时，代理设置为规则模式，避免本地ollama通过代理被调用。

【笔记】排查并解决Error in LLM call after 3 attempts: (status code: 502)-CSDN博客

这份笔记涵盖了从环境搭建到项目运行及问题解决的全流程。若在部署过程中还有疑问，或遇到其他状况，欢迎随时一起交流。