finrep-report/algo

finrep-algo-agent

Python 算法服务骨架：健康检查、/v1/outline/l1|l2、/v1/section 占位实现，便于与 Java pythonagent 联调。

本地运行

cd algo
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
uvicorn finrep_algo_agent.main:app --reload --host 0.0.0.0 --port 8002 --app-dir src

环境变量

复制 env.example 为 .env（可选）。主要项：

• FINREP_LLM_BASE_URL：OpenAI 兼容网关地址，如 https://api.openai.com/v1
• FINREP_LLM_API_KEY：密钥
• FINREP_LLM_MODEL：模型名
• FINREP_STUB_SKILLS=true：为 true 时 L1/L2/Section 返回固定占位数据，不调模型

推荐使用阿里云百炼 OpenAI 兼容模式（北京）：

• Base URL：https://dashscope.aliyuncs.com/compatible-mode/v1
• 文本生成模型（示例）：qwen-plus
• 向量模型（示例）：text-embedding-v3
• OCR 解析模型（示例）：qwen-vl-ocr

本项目已支持三类模型独立配置（均为 OpenAI 兼容 HTTP）：

• 文本生成：FINREP_LLM_*
• 向量 Embedding：FINREP_EMBEDDING_*
• OCR 解析：FINREP_OCR_*

如果三类模型共用同一个 API Key，可只填 FINREP_LLM_API_KEY；代码会在 Embedding/OCR 侧自动回退复用。

如何获取阿里云百炼 API Key

1. 进入阿里云百炼控制台（Model Studio）。
2. 开通并进入对应地域（建议与你部署环境一致）。
3. 在「API-KEY」或「密钥管理」页面创建 Key。
4. 复制 Key 填入 .env 的 FINREP_LLM_API_KEY（或分别填到 FINREP_EMBEDDING_API_KEY、FINREP_OCR_API_KEY）。
5. 重启服务使新环境变量生效。

参考文档：

• OpenAI 兼容模式调用千问
• OpenAI 兼容方式调用千问视觉模型

联调

• GET http://localhost:8002/health
• POST http://localhost:8002/v1/outline/l1（JSON 见 schemas）

与《MVP 需求文档》对齐的交互字段

• 一级大纲 POST /v1/outline/l1：请求体与需求文档「报告背景信息」「一级章节候选清单」一致：report_type、agreement_amount、enterprise_type、group_business_segments、industry_type、has_independent_report、independent_report_types、candidate_financing_tools、recommended_financing_tools、other_requirements、chapter_candidates（每项可含除 chapter_id/chapter_name 外的扩展字段，如重要性、适用条件，将原样写入清单文本供模型使用）。
• 二级大纲 POST /v1/outline/l2：除 chapter_name、chapter_no、chapter_paragraph_count_enum、leaf_chapter_candidates 外，需传入与需求文档「已确定的上游约束」「整体写作逻辑说明」对齐的 chapter_reason（一级该章 reason）、overall_logic（一级 overall_logic）。报告背景推荐整块传入 l1_task_snapshot（与 L1 请求同结构的 OutlineL1Request）；若不传，则使用本请求上的扁平字段（report_type、agreement_amount 等）拼背景。
• 段落生成 POST /v1/section：template_type 取值 info / analysis / metric / judgment 对应需求文档四类模板；overall_logic、chapter_logic、paragraph_position、task_input、data_package、paragraph_logic 对应模板中「橙/蓝」占位；example、notes 对应「示例」「其他注意事项」。

提示词正文位于 src/finrep_algo_agent/prompts/templates/*.j2，与需求文档摘录保持一致，后续仅以改模板版本迭代。