Starfish 研报分析和因子衍生教程

因子开发管理平台 Starfish 是面向专业投资团队的一站式量化投研分析平台，其研报分析助手提供了多项实用的功能，涵盖研报文件上传、因子自动解析、手动添加因子，以及基于数据库库表的因子函数生成和因子评价等。通过在上传研报后借助自动解析功能提取关键因子，或手动补充所需因子，再由分析助手调用数据库资源完成函数生成与评价，用户能够高效地开展研报分析工作。

本文将以简单的例子展示如何在 Starfish 因子开发管理平台中使用研报分析助手完成研报分析。研报分析功能依赖于部署在平台中的 AI 助手，因此在进行研报分析之前，需要先部署 AI 助手并进行配置，详细请参考智能助手部署手册。

1. 研报分析与衍生因子整体逻辑

Starfish 平台的研报分析与衍生因子功能，基于 AI Agent + 大语言模型（LLM）的协同工作机制，实现从研报理解、因子构建到因子评价的自动化流程。

1.1 流程速览

准备：配置默认模型和任务配额，由管理员配置并保存所需数据源映射。
输入研报：上传研报，选择解析得到的因子或手动补充因子，配置任务选项。
因子分析：Agent 提取因子定义和计算要求，并将结果保存到工作区。
数据配置：Agent 结合数据源映射、Data Skill 和 Relation Skill 解析数据需求、字段语义及数据关系，形成数据参数。平台标准工具完成具体取数和关联。
代码生成与验收：Agent 按需加载编码和复现相关 Skill，生成代码；系统执行代码，并通过 Result Checker 检查定义、数据和实现的一致性。失败时，根据反馈回退到相应阶段修正。
评价与保存：完成因子评价后查看结果，按需将代码存入研报草稿并保存到私有因子库，也可按现有入口创建衍生因子任务。

上述阶段用于说明任务推进过程。Agent 根据工作区当前状态选择下一步，失败时可能回退修正；工作区中的有效产物和状态用于记录进度及恢复任务。

1.2 AI 模型说明

研报分析与衍生因子功能中所使用的 AI 模型，默认等同于当前用户在 AI Chat 中配置的默认模型。创建研报分析任务时支持选择 AI 模型。

因此，在使用研报分析和衍生因子功能之前，需要先在 AI Chat 中确认并设置默认模型，以确保后续任务能够正常调用期望的模型能力。建议用户先进入 AI Chat 页面：

确认已有可用的模型配置
将期望使用的模型设置为默认模型

否则，研报分析任务可能会使用非预期模型，或因未设置默认模型而无法正常执行。

1.3 Skill 与知识库的作用

Skill 将因子分析、数据知识、数据关联、编码规范和静态检查等规则组织为可按需加载的能力包。Agent 使用 skill_read 读取当前阶段需要的内容，可在过程记录中查看相关调用。可选知识库配置仍按3.1.4说明使用；Skill 与 RAG 不应混为同一项配置。

2. AI 权限配置

在使用研报分析和因子衍生功能之前，管理员需要先为用户配置对应的 AI 权限。AI 权限配置分为两个部分：

AI 任务配额：用于控制用户可创建的 AI 任务数量及使用上限；
数据源映射：配置研报 Agent 可使用的数据来源、字段语义及取数范围。

配置入口统一位于系统管理的 AI 权限管理页面：

2.1 AI 任务配额

AI 任务配额用于限制用户在研报分析和因子衍生过程中的资源使用情况，避免因用户超额创建任务而导致大模型 API 被限流或产生过高的调用成本。管理员可以通过该功能，对用户可创建的 AI 任务数量进行统一管理和控制。

在 AI 任务配额页面中，管理员可以查看所有用户当前的 AI 任务使用情况，主要包含以下三项信息：

1）研报因子任务数量（已用 / 上限）：表示该用户已创建的研报因子任务数量及其最大允许数量。

研报因子任务数量 = 用户在研报中实际创建的因子任务数量。例如：

某篇研报中提取出 10 个因子
用户选择这 10 个因子并创建任务

则该用户共创建 10 个研报因子任务，使用量为 10。

2）衍生因子任务数量（已用 / 上限）表示该用户已创建的衍生因子任务数量及其上限。

衍生因子任务数量 = 创建衍生任务的母因子数量。例如：

对某一个研报因子创建衍生任务
设置衍生轮数为 10

则虽然最终生成了 10 个衍生因子，但仅计为 1 个衍生因子任务。

3）衍生因子轮数上限表示单个衍生因子任务允许进行的最大衍生轮数。

每一轮会生成一个新的衍生因子
轮数越高，生成的衍生因子数量越多
该值用于限制单个衍生任务的最大生成衍生因子数量

管理员可以通过以下两种方式修改用户的 AI 任务配额：

单用户配置：点击用户操作栏中的编辑按钮，对单个用户进行配额调整。

图 4. 图 2-3 用户 AI 任务配额设置
批量配置：选择多个用户后，点击右上角的批量设置，一次性为多个用户配置相同的配额规则。

配额配置保存后，将在用户下一次创建任务时生效，不会影响当前正在运行中的任务。

2.2 数据源映射

以股票日频行情为例，在系统管理 → AI 权限管理 → 数据源映射中点击“添加”，选择“内置数据源模板”，在“数据源模板”中依次选择股票、行情、日频，并确认自动填入的名称 stock.market.day。
选择本环境实际数据库和数据表，点击“读取表结构并创建”。
在详情中选择实际时间字段、证券字段及默认取数跨度，核对全部标准字段的真实源字段。按需将其他字段的映射方式设为“自定义字段”，在系统显示的固定前缀后填写字段后缀；无需提供给 Agent 的字段选择“不映射”。
点击“保存映射”，确认列表状态为“已保存”，再创建研报分析任务。完整字段说明、保存校验及管理操作参见“系统管理”的数据源映射。

2.3 查看 AI 权限用量

在创建研报分析或衍生因子任务之前，普通用户可以先查看自己当前的 AI 权限用量，以确认是否仍有可用配额，避免在创建任务时因超额而失败。

查看入口在研报分析的创建任务页面中，可以看到当前登录用户的 AI 权限用量信息。

3. 研报分析

研报分析作为 Starfish 平台研报分析助手的核心模块，通过 “创建任务 — 任务列表跟踪” 流程适配金融投研、量化交易等场景。创建任务时，用户可快速处理行业研报，提取或补充因子。任务列表支持全流程跟踪，用户可核查因子合理性、用可视化结果论证策略；量化团队能针对性解决任务失败问题，还可暂停调整代码提升因子代码生成效率，形成从因子提取到评价验证的闭环。

3.1 创建任务

点击研报分析助手下拉列表中的创建任务，进入研报分析任务创建界面。用户可以在该页面完成研报上传、因子解析、数据源配置以及任务参数设置等操作。

3.1.1 上传研报并编辑内容

在创建任务页面中，用户首先需要上传研报文件。

上传完成后，系统会在研报预览区域自动提取 PDF 中的文字内容并展示
用户可根据实际研究需求，对解析出的文本内容进行增删或修改
同时可以编辑当前任务的任务名称，以便后续在任务列表中区分和管理

3.1.2 因子解析与手动补充

点击因子解析按钮后，研报分析助手会基于研报内容自动解析因子。

若自动解析的因子完整且符合需求，可直接使用
若存在遗漏或不符合研究目标的情况，用户可以点击添加因子：
- 手动输入因子名称
- 填写对应的因子描述

通过自动解析与手动补充相结合的方式，可以确保因子定义更加准确。

3.1.3 数据源与字段配置

在创建任务 → 更多配置 → 数据设置中配置评价数据。因子计算所需数据由 Agent 在已配置映射的范围内解析；评价数据按以下方式选择：

不勾选“人工覆盖评价数据”：默认使用研报助手针对因子分析得到的评价数据源。
勾选“人工覆盖评价数据”：选择已保存的因子评价数据源映射，检查并按需调整评价价格列。评价数据应与因子的资产、频率及时间范围匹配。

同一篇研报中的因子可能具有不同频率。检查各因子使用的评价数据是否符合其频率和数据覆盖需求，尤其是在人工覆盖评价数据时。

3.1.4 启用知识库（RAG）增强分析能力（可选）

在创建任务时，用户还可以选择知识库，在任务执行过程中引入 RAG（检索增强生成）机制，以提升因子生成和代码修复的效果。当前支持以下两个 RAG 过程：

因子解释增强
- 在因子任务生成解释后
- 系统会将因子解释作为文本输入，在知识库中检索相似的因子实现说明
- 检索结果将作为上下文，传入第一次代码生成的提示词中
代码错误修复增强
- 当代码生成后出现错误信息时
- 系统会使用错误信息在知识库中进行检索
- 获取可能的解决方案，并将其传入下一轮代码生成的提示词中

3.1.5 因子结果入库配置（可选）

本节保存的是计算结果数据。代码草稿保存见3.2.4 保存研报代码草稿，不替代本节的结果表配置。

在创建任务时，用户还可以选择是否将运行成功的因子结果入库。若选择入库，需指定目标数据库表，并确保表结构满足以下要求：


字段名	字段类型
securityId	SYMBOL/STRING
tradeTime	TIMESTAMP
factorName	STRING
value	DOUBLE
updateTime	TIMESTAMP
username	SYMBOL/STRING

以下示例展示了一种常见的建表方式：

按研报任务成功时间（月）进行分区
按因子名称进行分区

db1 =database(, partitionType = VALUE, partitionScheme =[2025.01M]);
db2 =database(, partitionType = VALUE, partitionScheme =["factor1"]);
database(directory = 'dfs://factorFromReports', partitionType = COMPO, partitionScheme = [db1,db2], engine= `OLAP)

createPartitionedTable(dbHandle = database('dfs://factorFromReports'),table = table(1:0, ["securityId","tradeTime","factorName","value","updateTime","username"],["SYMBOL","TIMESTAMP","STRING","DOUBLE","TIMESTAMP","STRING"]),tableName = 'result',partitionColumns =["updateTime","factorName"])

这种分区方式适合以下场景：

按任务执行时间检查结果
按因子名称进行因子级别管理

如果业务场景更偏向于按行情时间或按任务创建人查询数据，则可根据实际需求选择其他分区方案。

3.1.6 启用衍生因子（可选）

对于当前创建的研报因子，用户可以选择是否开启衍生因子功能：

若开启，在研报因子任务成功后将自动创建衍生因子任务
可根据当前用户的 AI 权限设置，选择衍生因子的轮数
每一轮将基于上一轮结果生成新的衍生因子

3.2 任务列表与任务状态说明

在任务列表中可以查看任务的状态，状态为运行中表示正在运行，当状态显示为 “运行中” 时，表明任务正在进行。任何状态的任务都可以点击因子名称进入运行界面，可查看从研报中解析出的因子的解释、公式、生成的运行代码以及代码的迭代过程。这对于研究人员追溯因子的生成逻辑、验证因子的合理性具有重要意义。

进入因子任务详情后，可展开 Agent 工作区，查看工作区状态、因子定义、数据参数、因子代码、代码历史和 Agent 上下文。工作区中的检查结果与最近错误，是定位失败阶段的主要依据。

3.2.1 因子任务状态说明

每一个因子任务在执行过程中，可能处于以下几种状态。不同状态下，系统支持的操作也有所不同。


状态	备注	支持操作
运行中	因子任务正在运行中	可以查看详情，包含以下内容：因子公式因子解释因子代码的运行记录
中断	因子任务被手动暂停	可以查看详情，包含以下内容：因子公式因子解释因子代码的运行记录并且可以编辑代码并重新启动任务
失败	因子任务失败 AI 请求失败，可能因为以下原因：到达重试次数返回结果格式无法解析上下文超过模型限制等	可以查看生成成功的记录
生成评价中	因子生成结果通过执行检查和 Result Checker 静态验收后，再进入后续因子评价流程。	可以查看详情，包含以下内容：因子假设因子公式因子解释因子代码的运行记录最终结论
因子函数生成失败	评价任务中发现因子未成功生成	可以查看详情，包含以下内容：因子假设因子公式因子解释因子代码的运行记录最终结论并且可以重启因子任务，也就是将状态改为运行中；也可以修改最后一次代码，并重新启动任务
评价任务失败	评价任务中运行 Alphalens	可以查看详情，包含以下内容：因子假设因子公式因子解释因子代码的运行记录最终结论可以修改最后一次代码，并重新启动任务
成功	所有任务通过	可以查看详情，包含以下内容：因子假设因子公式因子解释因子代码的运行记录最终结论因子评价结果

3.2.2 任务结果与问题排查说明

当任务全部运行完成后，任务列表中的状态栏会展示最终结果。

成功

成功结果应包含通过执行检查和静态验收的因子代码，以及完成的因子评价结果。

图 11. 图 3-6 成功任务的因子解释与代码运行历史

图 12. 图 3-7 因子评价的 IC 指标与分组超额收益净值
评价任务失败或因子函数生成失败

通常是由于数据源缺失、因子定义不清晰、字段不匹配等原因导致。可以点击详情页中的查看错误信息查看具体的报错。

图 13. 图 3-8 因子函数生成失败的错误详情

发生失败时，先查看工作区检查反馈，区分数据配置、代码执行、静态验收与因子评价问题。


问题	优先检查	处理方向
映射不完整或取数为空	数据参数、字段映射、时间范围及检查反馈	补齐实际数据或映射，确认取数范围与数据覆盖一致。
代码执行成功但静态检查失败	因子定义、公式、窗口、字段语义、关联关系和输出	按检查给出的最早回退阶段修正，不以“能运行”作为完成依据。
因子评价失败	评价映射、价格列、频率、数据覆盖及错误信息	核对评价数据与因子结果的一致性。
重复失败或达到重试限制	工作区最近错误、检查结果和重试记录	定位根因后处理；不要无差别重复重启。

3.2.3 手动干预与代码调整

在因子任务运行过程中，如果用户在任务详情页面中发现自动生成的代码需要人工优化，可以：

手动暂停当前任务
对生成的代码进行修改
提交修改并重新启动任务

该机制为研究人员提供了较高的灵活性。在实际应用中，当研究人员基于经验判断代码仍有优化空间时，可以及时进行调整，从而使因子评价结果更符合研究预期，提高研报分析的整体质量。

3.2.4 保存研报代码草稿

在任务详情中，点击代码运行历史右侧的“存入草稿”，或点击页面右下角的草稿入口。
首次使用时，在“关联因子库草稿”弹窗中填写因子名称，并按需填写注释、属性和标签，点击“创建”。
在研报代码草稿中检查、编辑或粘贴因子代码，再点击“保存到因子库”。
看到保存成功提示后，进入因子与评价 → 我的因子，查看并继续管理、测试和使用对应私有因子。

操作界面及截图参见“研报分析助手”的保存因子代码草稿。

4. 衍生因子

衍生因子功能用于在已有研报因子的基础上，自动生成多个改进版本，并通过多轮迭代逐步优化因子表现，帮助研究人员找到 IC 值表现更优的因子方案。系统支持为每个衍生任务设置衍生轮数（根据用户权限）。在任务执行过程中，系统会按轮次依次生成新的衍生因子，并对每一轮结果进行评估。

衍生因子采用逐轮迭代优的方式生成。每一轮衍生因子都会在前一轮结果的基础上进行改进，而不是彼此独立生成。其核心逻辑可以概括为：

第 N 轮衍生因子 = 原始因子 + 第 1 至第 N−1 轮衍生因子的分析报告

系统会将历史轮次中已生成因子的公式和评价结论一并作为上下文输入，指导后续轮次的因子生成。

4.1 创建任务

系统提供三种创建衍生因子任务的方式。每个因子均可创建多轮衍生任务，具体轮数受用户 AI 权限配置限制。

方法一：在研报分析任务创建时，可以直接配置衍生因子

创建研报因子任务时，勾选生成衍生因子
设置需要的衍生轮数，当研报因子任务成功完成后，系统将自动开启对应的衍生因子任务，无需用户再次操作

方法二：从研报分析助手的因子任务列表中创建

在一个已完成的因子任务右侧操作栏中点击衍生因子
选择衍生轮数

方法三：从衍生因子任务列表中继续衍生

在列表中选择一个完成的衍生因子任务，在操作栏点击衍生因子
设置衍生轮数

创建成功后的任务结构说明

衍生因子任务创建成功后，任务列表中将展示如下结构：

新增一个父节点，表示原始因子及其基本信息
在父节点下方，生成 N 条子任务记录，对应 N 轮衍生过程：
- 第一轮：任务立即进入运行中状态
- 后续轮次：初始状态为等待中，前一轮完成后自动激活

4.2 任务列表

衍生因子任务的状态体系与研报因子任务保持一致，用户可在任务执行过程中随时查看进度和结果。详情可以参照 3.2。

除了查看单个衍生因子的任务详情外，系统还支持查看整个衍生任务的综合报告。

点击原始因子名，进入任务详情；
页面内容包括：
- 各轮衍生因子的 IC 值表格
- 不同轮次 IC 表现的对比柱状图
- 系统生成的各轮因子表现总结

通过这些信息，用户可以直观地对比不同轮次因子的表现，从而判断哪一轮衍生效果最优，为后续策略研究和落地提供依据。

5. 注意事项与准确性说明

在 Starfish 平台中，一个完整的因子任务不仅包含因子计算代码的生成，还包括后续的因子评价过程。因此，本章中的注意事项同时适用于因子生成阶段和因子评价阶段。在使用因子平台的 AI 研报分析功能时，需要注意 AI 自动生成的因子计算代码，其准确性会受到多方面因素的影响。该功能更适合用于快速原型验证和研究辅助，而不应被视为对研报因子逻辑的完全自动复现。

5.1 因子生成阶段

在因子生成阶段，AI 会基于研报内容、因子描述以及所选数据源结构，自动生成因子计算代码。影响该阶段生成准确性的主要因素包括以下几个方面：

模型自身的理解与代码生成能力：AI 对研报内容的理解深度，以及将自然语言描述转化为可执行代码的能力，直接决定了生成结果的上限。
因子计算逻辑的复杂程度：当研报中的计算逻辑较为简单、步骤清晰、时间频率单一时，AI 通常能够较准确地生成对应代码。而当因子涉及多层计算、条件分支、滚动窗口或跨频率处理时，理解和还原的难度会显著提升。
输入数据源的完整性与字段语义：因子计算往往依赖具有明确经济含义的特定字段。如果输入数据中缺失关键字段，或字段含义不直观，AI 即使生成可运行代码，也可能在经济意义上偏离研报原意。

5.1.1 研报文本信息对模型数据选择的潜在影响

部分研报标题或正文中包含明确的日期信息（如发布日期或研究时间点）。模型在理解研报内容时，可能会将这些日期误认为因子计算所需的数据时间范围，并在生成代码时自动引入时间或标的筛选条件。

当实际数据源中不存在对应时间段的数据，或数据覆盖范围不足时，因子计算阶段可能从一开始就无法获取有效数据，从而导致后续计算或评价失败。

当取数结果为空时，优先检查工作区中的数据参数、映射配置、默认取数跨度以及实际数据覆盖范围，再依据检查反馈修正相关阶段。

5.1.2 数据字段缺失带来的逻辑偏差

当因子依赖的字段未被映射或真实数据缺失时，应补充正确的数据及字段映射，或重新确认因子定义和可行性，不应将近似字段替代视为复现成功。Result Checker 会检查必要字段、数据可行性及定义与实现的一致性；用户仍需核对检查结论和因子的经济含义。

5.1.3 复杂因子组合场景的注意事项

对于需要将多个中间因子进行组合、修正或再加工的复杂因子结构，AI 在自动复现完整研报逻辑时面临更高难度。

在这类场景中，生成的代码往往能够正常运行并产出结果，但在聚合频率、计算顺序或数据依赖关系等细节上，仍可能与研报存在系统性偏差，从而影响后续的实证回测表现。

5.2 因子评价阶段

当前因子评价使用的是 Starfish 平台内置的 Alphalens 评价模板。在因子评价阶段，需要重点关注以下几个方面，这些问题往往直接决定评价是否能够顺利完成以及结果是否可靠。

5.2.1 因子结果结构与字段约定

因子评价模块对因子结果表的字段结构存在明确约定。评价阶段要求因子结果表中至少包含以下字段：


字段名称	类型	含义
securityId	STRING/SYMBOL	标的代码
tradeTime	TIMESTAMP/DATE	时间
factorname	STRING/SYMBOL	因子名称
value	DOUBLE/INT	因子值

当因子结果表中的列名与评价模块预期不一致时，即使字段含义本身正确，也可能导致评价阶段无法识别关键字段，从而直接失败。此外，如 5.1.1 中提到的错误过滤条件，也可能导致因子结果返回空表。这种情况下，因子生成阶段可能显示为成功，但在评价阶段会直接失败。

因此，在出现字段识别或评价失败问题时，应优先检查因子结果表的结构是否符合平台约定。

5.2.2 因子数据与评价数据源的一致性要求

用于因子评价的历史价格数据，其时间戳需要覆盖因子数据中的所有时间点，并且在时间长度上不应短于因子数据，才能正确计算 IC 值、分组收益等评价指标。

同时，因子数据的时间频率需要与用于评价的历史价格数据频率保持一致。例如，分钟频因子应使用分钟频价格数据进行评价，日频因子应使用日频价格数据。

使用默认解析的评价数据源时，可结合任务结果核对所选数据；使用人工覆盖时，应主动检查所选映射、评价价格列、频率及时间覆盖。自动解析与静态验收不能替代对研究结果的业务核对。

在平台实现中，因子评价会基于“资产代码 + 时间”两列进行 asof join。这意味着，如果因子表中的部分记录未能准确匹配到对应的价格数据，这种情况并不一定会直接导致评价失败，但可能对最终评价结果产生偏差。因此，当评价结果异常时，建议重点检查因子数据与价格数据在时间维度上的覆盖关系。

5.2.3 横截面样本规模不足的问题

部分因子在某些时间点仅对极少数标的生成了有效值。在这种情况下，即使因子计算阶段成功完成，评价阶段在进行 IC 计算或分层分组时，也可能因横截面样本数量不足而失败。

同样，在进行分层评价时，如果因子值分布过于集中、缺失值较多，或整体样本规模偏小，可能导致分组后无法构建有效的分层区间，从而引发评价失败。