本作品采用知识共享 署名-非商业性使用-相同方式共享 4.0 国际许可协议授权。

股票数据洞察应用

本项目展示了如何利用代理式检索增强生成（RAG）工作流，从新闻和金融数据中提取关于特定公司及整个股票市场的洞察。它结合了大型语言模型（LLM）、ChromaDB 向量数据库、LangChain、LangChain 表达式语言（LCEL）以及 LangGraph，以提供全面的分析报告。

功能特性

• 股票表现可视化：展示所选股票的历史表现图表。
• 属性级数据检索：获取与特定股票相关属性的详细信息。
• 新闻聚合：呈现与特定股票或公司相关的通用新闻或主题文章。

高层次架构

实现方法

异步爬取

1. 新闻数据：定期异步爬取预定义股票集合的新闻数据，并将信息存储在 MongoDB 中。这些文档会同步到 ChromaDB，以便 LLM 进行语义搜索，从而检索与特定股票或公司相关的信息。
2. 财务数据：定期异步爬取选定股票的财务数据，并将信息存储在 PostgreSQL 数据库中。

LangGraph 工作流

新闻数据 RAG 图

一个代理式 RAG 图，用于在向量数据库（来自 MongoDB 的同步文档）中搜索股票相关新闻数据；若未找到相关文档，则执行网络搜索。

该图包含以下节点：

• 从数据库检索新闻 (retrieve_news)：利用 LLM、LangChain 和检索工具，在向量数据库中对特定股票主题的相关文档进行语义搜索。
• 文档评分 (grade_documents)：评估上一步检索到的文档质量，并为其相关性打分。通过条件边决定是直接生成结果，还是在文档不相关时执行额外的网络搜索。
• 网络搜索 (web_search)：使用集成于 LangChain 的 TavilySearch 工具及 LLM 调用，执行网络搜索。
• 生成结果 (generate_results)：根据用户查询及先前步骤中检索到的文档生成最终结果。

股票数据 RAG 图

一个代理式 RAG 图，用于在 SQL 数据库（PostgreSQL）中搜索股票的财务数据。

该图包含以下节点：

• 生成 SQL 查询 (generate_sql)：利用 LLM 和 LangChain 根据用户输入生成 SQL 查询。
• 执行 SQL 查询 (execute_sql)：执行上一步生成的 SQL 查询，从数据库中获取数据。
• 生成结果 (generate_results)：利用 LLM 根据用户查询及前一步获取的数据生成最终结果。

股票数据图表 RAG 图

一个代理式 RAG 图，用于从 SQL 数据库（PostgreSQL）中检索股票的财务数据，并生成可视化图表。

该图由以下节点组成：

• 生成 SQL 查询 (generate_sql)：使用 LLM 和 LangChain 根据用户输入创建 SQL 查询。
• 执行 SQL 查询 (execute_sql)：运行之前生成的 SQL 查询，从数据库中获取数据。

API 接口

有关详细的 API 规范，请参阅随附的 openapi.json 文件。

价格统计 (GET /stock/{ticker}/price-stats)

获取特定股票代码的价格统计信息。

参数：

• ticker (str)：股票代码。
• operation (str)：要执行的操作（例如，“最高”、“最低”、“平均”）。
• price_type (str)：价格类型（例如，“开盘价”、“收盘价”、“最低价”、“最高价”）。
• duration (int)：天数。

返回：

• 字典：包含请求统计信息的股票数据。

参数说明：

• ticker：字符串 - 股票代码
• operation：字符串 - 操作类型：“最高”、“最低”、“平均”
• price_type：字符串 - 价格类型：“开盘价”、“收盘价”、“最低价”、“最高价”
• duration：字符串 - 时间范围（天数）：“1”、“7”、“14”、“30”

图表 (GET /stock/{ticker}/chart)

获取特定股票的价格统计数据，并返回相应的直方图或图表。

参数：

• ticker (str)：股票代码。
• price_type (str)：价格类型（例如，“开盘价”、“收盘价”、“最低价”、“最高价”）。
• duration (int)：天数。

返回：

• 字典：包含请求统计信息的股票数据。

参数说明：

• ticker：字符串 - 股票代码
• price_type：字符串 - 价格类型：“开盘价”、“收盘价”、“最低价”、“最高价”
• duration：字符串 - 时间范围（天数）：“1”、“7”、“14”、“30”

按主题获取新闻 (GET /news/{ticker})

获取特定股票的相关新闻。

参数：

• ticker (str)：股票代码。
• topic (str)：要获取新闻的主题。

返回：

• 字典：与特定股票相关的新闻内容。

参数说明：

• ticker：字符串 - 股票代码
• topic：字符串 - 新闻主题

根路径 (GET /)

应用程序的根页面/首页。

参数说明：

无参数

类图

图片

有关可视化内容，请参阅 images/ 目录中的图片。

测试框架

该项目采用 pytest 框架进行自动化测试，以确保所有模块都经过充分测试，从而保持系统的可靠性和健壮性。测试设置的主要特点包括：

• 全面的测试用例：为每个模块编写测试用例，确保覆盖整个应用程序。
• 易于使用：只需运行以下命令即可执行所有测试：

pytest

• 测试报告：框架会为每次测试运行生成详细的报告，突出显示成功和失败的情况。

此测试设置可确保在添加新功能或更新现有功能时，应用程序始终保持稳定和正常运行。

可观测性与追踪

为监控应用性能并调试与大语言模型相关的流程，该项目集成了 LangSmith 追踪功能。这使得所有大语言模型调用都能被详细追踪，从而深入了解应用的执行流程。

关键特性：

• 大语言模型调用追踪：跟踪与大语言模型的所有交互，包括输入、输出和执行时间。
• 调试辅助：帮助识别大语言模型工作流中的瓶颈或错误。
• LangSmith 控制台：提供友好的用户界面，用于可视化和分析追踪数据。

工作原理： LangSmith 追踪已无缝集成到应用中。所有 RAG 工作流，包括新闻 RAG 图、股票数据 RAG 图以及股票数据图表 RAG 图，均使用 LangSmith 来提供可操作的可观测性洞察。

参考资料

• LangGraph：一个用于构建具有状态的多智能体应用的库，支持创建智能体及多智能体工作流。
• LangChain 表达式语言 (LCEL)：一种声明式的链式组合方法，能够实现复杂工作流的无缝集成与优化。

本项目展示了如何整合先进的 AI 工作流，以对金融和新闻数据进行深入分析，为用户提供一套全面的股市评估工具。

stocks-insights-ai-agent 快速上手指南

本指南帮助中国开发者快速部署并使用 stocks-insights-ai-agent，这是一个基于 Agentic RAG（检索增强生成）工作流的股票数据洞察应用。它利用大语言模型（LLM）、ChromaDB、LangChain 和 LangGraph 来分析新闻和财务数据。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

系统要求

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Python: 版本 3.9 或更高
• 数据库:
  • MongoDB (用于存储新闻数据)
  • PostgreSQL (用于存储财务数据)
• 向量数据库: ChromaDB (通常随项目自动初始化，也可独立部署)

前置依赖与配置

1. API Keys: 您需要准备以下服务的 API 密钥：

   • LLM 提供商 (如 OpenAI, Anthropic 等)
   • Tavily Search (用于网络搜索补充)
   • 股票数据源 (根据项目具体实现配置)

2. 环境变量: 在项目根目录创建 .env 文件，配置必要的密钥和数据库连接字符串：

   OPENAI_API_KEY=your_openai_key
   TAVILY_API_KEY=your_tavily_key
   MONGODB_URI=mongodb://localhost:27017
   DATABASE_URL=postgresql://user:password@localhost:5432/stockdb
   LANGSMITH_API_KEY=your_langsmith_key # 可选，用于追踪观测
   

3. 国内加速建议:

   • 如果使用 pip 安装依赖，建议使用清华或阿里镜像源加速下载。
   • 若涉及外部 API 调用受阻，请配置合适的网络代理。

安装步骤

1. 克隆项目代码

   git clone <repository-url>
   cd stocks-insights-ai-agent
   

2. 创建并激活虚拟环境

   python -m venv venv
   source venv/bin/activate  # Windows 用户使用: venv\Scripts\activate
   

3. 安装依赖包 推荐使用国内镜像源加速安装：

   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

4. 初始化数据库 确保 MongoDB 和 PostgreSQL 服务已启动，并运行项目提供的初始化脚本（如有）：

   # 示例：运行数据迁移或建表脚本
   python scripts/init_db.py
   

5. 验证安装 运行测试套件以确保环境配置正确：

   pytest
   

基本使用

项目启动后，主要通过 API 接口进行交互。以下是几个核心功能的最简使用示例。

1. 启动服务

假设项目使用 FastAPI 或类似框架，启动命令通常为：

uvicorn main:app --reload

服务默认运行在 http://127.0.0.1:8000。

2. 获取股票价格统计

查询特定股票代码（如 "AAPL"）在過去 7 天的最高收盘价：

请求示例 (curl):

curl -X GET "http://127.0.0.1:8000/stock/AAPL/price-stats?operation=highest&price_type=close&duration=7"

参数说明:

• ticker: 股票代码 (e.g., "AAPL", "TSLA")
• operation: 操作类型 ('highest', 'lowest', 'average')
• price_type: 价格类型 ('open', 'close', 'low', 'high')
• duration: 时间跨度天数 ('1', '7', '14', '30')

3. 获取股票走势图

获取特定股票的價格直方图/图表数据：

请求示例 (curl):

curl -X GET "http://127.0.0.1:8000/stock/AAPL/chart?price_type=close&duration=30"

4. 查询特定主题的新闻

利用 RAG 工作流查询与某股票相关的特定主题新闻（例如 "earnings"）：

请求示例 (curl):

curl -X GET "http://127.0.0.1:8000/news/AAPL?topic=earnings"

注：此接口会先在向量数据库检索，若无结果则自动触发网络搜索。

5. 观测与调试 (可选)

如果配置了 LANGSMITH_API_KEY，您可以访问 LangSmith Dashboard 查看详细的 LLM 调用链路、延迟及中间推理过程，便于调试 RAG 工作流。