企业官网建设流程全解析

GS Quant Basket 因子风险报告创建指南：add_factor_risk_report 实战解析

【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant

本文基于 gs-quant 开源仓库（Python quantitative finance toolkit）中Basket.add_factor_risk_report的 API 文档，结合其底层源码、数据模型与测试用例，系统讲解如何为自定义篮子（Custom Basket）创建并调度因子风险报告（Factor Risk Report），包括方法签名、参数语义、权限前置条件、完整调用示例以及与之对应的删除操作，帮助读者在因子归因与风险监控场景中直接落地使用。

一、功能定位：为篮子调度因子风险报告

在 gs-quant 中，Basket（源码类定义）表示一个随时间演化的证券组合，可通过现金或衍生品市场交易。对于自建篮子，投资者通常需要持续监控其相对某个风险模型（Risk Model）的因子暴露与风险分解，例如市场因子、行业因子、风格因子等。

Basket.add_factor_risk_report(risk_model_id, fx_hedged)正是用于完成这一诉求的入口：为一篮子创建并调度（schedule）一个全新的因子风险报告。调用成功后，平台会根据所选风险模型周期性生成该篮子的因子风险分解结果，供后续风险分析、业绩归因等场景使用。

二、方法签名与参数说明

方法定义位于 gs_quant/markets/baskets.py#L634-L658：

@_validate(ErrorMessage.UNINITIALIZED, ErrorMessage.NON_ADMIN) def add_factor_risk_report(self, risk_model_id: str, fx_hedged: bool): """ Create and schedule a new factor risk report for your basket :param risk_model_id: risk model identifier :param fx_hedged: Assume basket is FX hedged **Usage** Create and schedule a new factor risk report for your basket **Examples** >>> from gs_quant.markets.baskets import Basket >>> >>> basket = Basket.get("GSMBXXXX") >>> basket.add_factor_risk_report('AXUS4M', True) **See also** :func:`delete_factor_risk_report` """ payload = CustomBasketRiskParams(risk_model=risk_model_id, fx_hedged=fx_hedged) return GsIndexApi.update_risk_reports(payload)

该方法返回GsIndexApi.update_risk_reports(...)的调用结果（见下文"底层调用链"）。

三、前置条件与权限校验

add_factor_risk_report在函数体执行前，会经过装饰器_validate(ErrorMessage.UNINITIALIZED, ErrorMessage.NON_ADMIN)的校验。该校验器定义在 gs_quant/markets/baskets.py#L79-L105，会在方法真正执行前确认：

1. 篮子初始化完成：若Basket尚未完成初始化，将抛出MqError（对应ErrorMessage.UNINITIALIZED）；
2. 管理员权限：执行者必须被篮子所有者正确授权（entitlement），否则抛出MqError，错误信息为ErrorMessage.NON_ADMIN："You are not permitted to perform this action on this basket. Please make sure the basket owner has entitled your application properly if you believe this is a mistake"。

因此，在调用前需要确保：

• 已通过GsSession建立 Marquee 会话（客户端凭据与应用凭据均可），会话配置可参考仓库 session.py；
• 当前应用对目标篮子具备管理员级操作权限；
• 使用Basket.get("GSMBXXXX")获取到已初始化的篮子实例（GSMBXXXX为篮子标识符占位，实际替换为真实篮子 ID）。

四、完整使用示例

结合源码 docstring 中的示例，一个可复制的完整调用流程如下：

from gs_quant.session import GsSession from gs_quant.markets.baskets import Basket # 1. 建立会话（实际凭据请替换） GsSession.use(client_id="...", client_secret="...", scopes=("read_product_data", "modify_product_data")) # 2. 获取篮子实例 basket = Basket.get("GSMBXXXX") # 3. 基于指定风险模型创建并调度因子风险报告，且假设篮子已做 FX 对冲 basket.add_factor_risk_report('AXUS4M', True)

要点说明：

• Basket.get(...)是获取篮子实例的标准入口，其实现（baskets.py#L157-L160）会调用内部接口拉取篮子资产信息并完成初始化；
• fx_hedged=True表示报告在计算因子暴露时按 FX 已对冲处理；若篮子未做外汇对冲，则传False。

五、底层调用链与数据模型

add_factor_risk_report并非直接发起 HTTP 请求，而是通过目标模型（Target Model）与 API 客户端完成序列化与传输，调用链如下：

1. 构造请求载荷

方法将两个参数封装为CustomBasketRiskParams数据类实例：

payload = CustomBasketRiskParams(risk_model=risk_model_id, fx_hedged=fx_hedged) return GsIndexApi.update_risk_reports(payload)

CustomBasketRiskParams定义于 gs_quant/target/indices.py#L143-L150，是一个基于dataclass+ camelCase JSON 序列化的目标模型：

@handle_camel_case_args @dataclass_json(letter_case=LetterCase.CAMEL) @dataclass(unsafe_hash=True, repr=False) class CustomBasketRiskParams(Base): risk_model: Optional[str] = field(default=None, metadata=field_metadata) fx_hedged: Optional[bool] = field(default=None, metadata=field_metadata) delete: Optional[bool] = field(default=None, metadata=field_metadata) name: Optional[str] = field(default=None, metadata=name_metadata)

可见该模型还预留了delete（用于删除报告）与name（自定义报告名）字段，为风险报告的增删改查提供了统一的数据载体。

2. 请求 API 客户端

随后调用 gs_quant/api/gs/indices.py#L129-L134 中的GsIndexApi.update_risk_reports：

@classmethod def update_risk_reports(cls, _id: str, inputs: CustomBasketRiskParams): """Create, modify, or delete a custom basket factor risk report""" url = f'/indices/{_id}/risk/reports' inputs = CustomBasketsRiskScheduleInputs(risk_models=inputs) return GsSession.current.sync.post(url, payload=inputs)

注意：这里的_id实际由Basket.id注入，最终请求为对/indices/{basket_id}/risk/reports的POST；载荷被进一步包装为CustomBasketsRiskScheduleInputs（target/indices.py#L269-L276），其核心字段risk_models为CustomBasketRiskParams元组，支持一次调度多个风险模型。调用使用GsSession.current.sync.post进行同步请求。

3. 权限与初始化校验的落地位置

_validate装饰器会在调用进入函数体之前检查Basket内部的错误消息列表（_Basket__error_messages），只有校验通过才会真正执行update_risk_reports。这一设计将"权限/状态检查"与"业务逻辑"解耦，是使用该方法时必须理解的执行时序。

六、关联操作：删除因子风险报告

与add_factor_risk_report成对出现的是delete_factor_risk_report（baskets.py#L660-L683），官方文档亦通过See also交叉引用：

@_validate(ErrorMessage.UNINITIALIZED, ErrorMessage.NON_ADMIN) def delete_factor_risk_report(self, risk_model_id: str): """ Delete an existing factor risk report for your basket :param risk_model_id: risk model identifier for the report you'd like to delete """ payload = CustomBasketRiskParams(risk_model=risk_model_id, delete=True) return GsIndexApi.update_risk_reports(payload)

两方法的差异仅在于载荷中是否设置delete=True：

• add_factor_risk_report：CustomBasketRiskParams(risk_model=..., fx_hedged=...)，执行创建/调度；
• delete_factor_risk_report：CustomBasketRiskParams(risk_model=..., delete=True)，执行删除。

两者共用同一 API 端点/indices/{basket_id}/risk/reports，体现了"同一资源、不同动作语义"的设计。完整删除示例：

basket = Basket.get("GSMBXXXX") basket.delete_factor_risk_report('AXUS4M')

七、测试验证：行为与错误分支

仓库在 gs_quant/test/markets/test_baskets.py#L299-L329 中提供了test_update_risk_reports测试，覆盖了该功能的关键行为：

1. 未初始化篮子：调用add_factor_risk_report/delete_factor_risk_report均抛出MqError，错误信息匹配ErrorMessage.UNINITIALIZED.value；
2. 非管理员用户：以无管理权限用户调用同样抛出MqError，匹配ErrorMessage.NON_ADMIN.value；
3. 正常添加：basket.add_factor_risk_report('AXUS4M', False)后断言GsIndexApi.update_risk_reports被以CustomBasketRiskParams(risk_model='AXUS4M', fx_hedged=False)载荷调用；
4. 正常删除：basket.delete_factor_risk_report('AXUS4M')断言载荷为CustomBasketRiskParams(risk_model='AXUS4M', delete=True)。

该测试同时验证了两类错误分支与两类成功分支，可作为读者理解参数语义与权限模型的行为参考（运行方式：pytest gs_quant/test/markets/test_baskets.py -k test_update_risk_reports）。

八、使用注意事项与最佳实践

• 风险模型标识符：risk_model_id需为平台中已发布可用的风险模型 ID（如示例中的'AXUS4M'）。若模型不存在或当前应用无访问权限，请求将失败，建议先确认模型可用性；
• FX 对冲假设：fx_hedged直接决定报告对 FX 因子的处理方式，需与篮子的实际对冲安排保持一致，否则风险分解中的 FX 暴露将失真；
• 权限模型：创建/删除风险报告均属管理操作，必须在应用 entitlement 中包含对应篮子，并由篮子所有者正确授权；
• 与轮询配合：创建报告属于异步调度类操作，可结合Basket的poll_report（baskets.py#L355-L357）等轮询机制跟踪后续报告生成状态。

九、相关文档与资源

• 本文主题文档：docs/functions/gs_quant.markets.baskets.Basket.add_factor_risk_report.rst
• 配套删除操作文档：docs/functions/gs_quant.markets.baskets.Basket.delete_factor_risk_report.rst
• 篮子类其他方法文档目录：docs/functions
• 核心实现：gs_quant/markets/baskets.py、gs_quant/api/gs/indices.py、gs_quant/target/indices.py
• 测试用例：gs_quant/test/markets/test_baskets.py

【免费下载链接】gs-quantPython toolkit for quantitative finance项目地址: https://gitcode.com/GitHub_Trending/gs/gs-quant