life-echo/api/docs/llm-json-mode.md

LLM JSON 模式使用约定

本文档说明 Life Echo API 中 结构化输出 与 自然语言输出 的分工，以及与 DeepSeek JSON Output 的对齐方式。

实现位置

• 绑定方式：app/core/langchain_llm.py 中的 bind_json_object_mode（等价于 response_format={"type": "json_object"}）。禁止使用已废弃的 model_kwargs={"response_format": ...} 绑定方式（见 app/adapters/llm/deepseek.py 注释）。
• 统一调用：invoke_json_object / ainvoke_json_object（同文件）在 JSON 模式下提供空内容检测、可选一次重试与结构化日志（agent、prompt_sha12）。

何时必须使用 json_object

以下路径需要稳定 json.loads / 下游解析，必须通过 bind_json_object_mode 或 invoke_json_object / ainvoke_json_object 调用：

能力	代码入口
用户资料字段抽取	ProfileAgent.extract_profile_from_message
回忆录阶段与 slots 抽取	ExtractionAgent.extract
叙事段落 JSON（paragraphs）	NarrativeAgent.generate_narrative
Story 路由 / 批量规划	StoryRouteAgent.decide / plan_batch
回忆录配图 prompt	MemoirImagePromptService.build_prompt / build_cover_prompt

何时保持普通文本（禁止强行 JSON）

• 访谈对话、资料追问开场与跟进：自然口语与 [SPLIT] 分条，使用 ChatOpenAI 默认输出（InterviewAgent、ProfileAgent 中非 extraction 方法）。
• 章节分类、创意标题等若仍为纯文本解析：由业务选择是否后续改为小 JSON（见产品决策）。

DeepSeek 官方建议对齐

1. response_format：已由 bind_json_object_mode 设置。
2. Prompt 中应包含 json 字样及与解析代码一致的 字段示例（各 prompts_*.py 中维护）。
   集中兜底：ensure_json_object_prompt_has_json_keyword 在 invoke_json_object / ainvoke_json_object 与 llm_json_call / allm_json_call 发请求前会检测；若整段 prompt 中仍无子串 json（大小写不敏感），会自动追加一行中文 JSON 说明，避免 OpenAI/DeepSeek 返回 400。
3. max_tokens：在 invoke_json_object(..., max_tokens=...) 与绑定处统一传入；长叙事等场景按需调大。
4. 偶发空内容：由 invoke_json_object 记录并重试一次；仍失败则由各 Agent 既有 try/except 回退。

架构注意

• app/core 仅承载跨切 LLM 约定，不依赖 features/* 或具体 Agent。
• Service 层通过 get_llm_provider().langchain_llm 获取 Runnable，不直接 import adapters。