本技能文档是一份构建生产级 AI 集成后端的综合指南，核心目标是在多供应商环境下实现稳定、可配置、可回退的 AI 服务。资料涵盖架构原则、系统数据流、数据库模型、回退机制、区域配置、提示词模板与外部 API 集成等信息。
一、核心架构原则 文档提出六项原则：1）多供应商设计——永远不要依赖单一供应商，保持回退链，设计供应商无关的接口来抽象各厂商实现，在高端模型失败时优雅降级（例如 GPT-4 → GPT-3.5 → Gemini-Flash），用配置驱动供应商选择而非硬编码，并支持同时使用多供应商做 A/B 测试与成本优化。2）关注点分离——分为模型层（Django ORM：机器人、LLM 配置、提示词、会话）、服务层（各供应商集成）、辅助层（提示词渲染、回退路由、响应处理）、网关层（集中式 JWT 认证的 LLM 访问服务）和 API 层（天气、占星、金融等外部 API 管理器）。3）配置优于代码——LLM 配置（供应商、模型、温度、token）存入数据库，无需重新部署即可切换配置实现 A/B 测试，通过 metadata 字段按机器人定制 AI 行为，用 is_active 标记即时切换。4）提示词工程最佳实践——基于模板的变量替换（{{variable_name}}）、集中式提示词管理与业务逻辑分离、支持系统级变量与用户级变量、基于 YAML 的结构化提示词、函数映射用于动态变量解析。5）回退与韧性——每个供应商都有回退链，最终以可靠的通用回退（如 Gemini-Flash）结尾，回退继承系统指令与区域配置，支持同供应商与跨供应商回退，AWS Bedrock 支持区域感知回退。6）安全与认证——内部 LLM 网关使用 JWT，token 缓存（缓存时长为 token 过期时间减 2 秒），API 密钥来自环境变量，服务间使用签名载荷认证。
二、系统架构与数据流 文档给出完整请求链路：用户聊天请求 → API 端点（校验输入、检查会话）→ 会话管理器（创建/恢复会话、锁定定价）→ 外部 API 层（按需获取占星、天气等数据，含多级缓存：实例→分布式→数据库，缓存未命中则调用外部 API，并经历校验→归一化→丰富→格式化流水线）→ 提示词构建器（加载机器人 LLM 配置、渲染模板、组装上下文、构建最终提示词）→ LLM 网关管理器（获取/生成缓存 JWT、构建回退链、POST 到内部网关 /v1/generate/）→ 内部 LLM 网关（校验 JWT、路由到主供应商、失败依次尝试回退）→ 响应处理（解析、校验、入库）→ 计费（计算单位、检查钱包余额、扣款、记录交易）→ 保存到数据库 → 返回用户。 文档还列出多供应商路由示例，如 Gemini 2.5-Pro 回退到 Gemini 2.5-Flash、Gemini 2.0-Flash；AWS Bedrock Deepseek-v3（ap-south-1 区域）回退到 Byteplus Deepseek-v3、Gemini 2.0-Flash；Byteplus 回退到 Gemini 2.0-Flash。
三、数据库模型设计 Bot 模型包含 uuid、user 外键、名称、slug、描述、头像、状态、类型、rank、metadata（JSONField，存 required_fields、pricing 等）、时间戳与软删除 deleted_at。设计决策包括用 metadata 实现灵活的单机器人配置、软删除、slug 自动生成、rank 自定义排序。BotLLMConfig 模型包含 bot 外键、prompt（支持 {{变量}} 模板）、model_name、llm_provider、温度、top_p、top_k、max_output_tokens、is_active、metadata（存 region_name、tools 等）。其 save 方法保证每个机器人只有一个活跃配置。BotLLMProvider 枚举包含 openai、gemini、anthropic、groq、ai-sdk、bedrock、byteplus、openrouter。
四、回退机制 文档给出 get_fallback_routing 函数示例，根据主供应商与模型生成回退链，每个回退项含 provider、model、retry、system_instruction，Bedrock 额外含 region_name。规则为：Gemini 2.5-Pro 回退到 Gemini 2.5-Flash 再到 Gemini 2.0-Flash；Byteplus 回退到 Gemini 2.0-Flash；Bedrock 的 deepseek.v3-v1:0 回退到 Byteplus deepseek-v3 再到 Gemini 2.0-Flash；无论何种情况最终都追加通用回退 Gemini 2.0-Flash。执行时先调主供应商，失败则按链尝试，全部失败抛出异常。设计原则包括通用回退兜底、优先同供应商更便宜的模型、必要时跨供应商、回退继承系统指令、区域感知、回退内不重试。
五、区域配置 AWS Bedrock 通过 BotLLMConfig 的 metadata 中的 region_name 指定区域，并可将回退链扩展到多个 AWS 区域（如 ap-south-1、us-east-1、eu-west-1），最后再追加非 Bedrock 回退。区域选择可基于用户位置或机器人配置确定主区域，再指定备用区域。
六、提示词模板 提示词模板系统通过 PromptTemplateHelper.render_template 方法将 {{变量}} 替换为实际值，示例为 "Hi {{user_name}}, today is {{current_date}}."。文档还提及动态变量、函数映射、YAML 结构化提示词等主题，但资料中仅给出索引与部分实现，其余细节暂未提供。