商业 LLM API 技术方案

# 商业 LLM API 技术方案

1. 覆盖范围

商业 LLM API 为 RAGFlow 和 LLM-WIKI 控制面提供模型能力。

LLM-WIKI 产品	模型支撑能力
文档迭代智能体	文档重写、结构化、补全、摘要
问答产品	基于检索上下文生成答案
反馈与任务产品	归因、归类、生成改进任务草稿
配置管理产品	模型、预算、用途分层配置

2. 如何购买

MVP 不在蓝图层固定单一模型供应商，但实施层必须选择一个默认接入方式，否则 RAGFlow、预算、密钥和验收无法落地。

MVP 默认实施策略：

• 模型供应商由 RAGFlow 管理。
• LLM-WIKI 不直接保存模型 key，不把模型 SDK 散落到控制面代码中。
• 默认优先支持 OpenAI-compatible endpoint，便于在 OpenAI、兼容网关或其他兼容供应商之间切换。
• 若现有 RAGFlow 已配置可用模型，MVP 直接复用现有配置，不强制迁移。

购买方式：

供应商类型	用途
OpenAI API	通用问答、文档整理、工具调用
Anthropic API	长文本理解、文档改写、审查
Gemini API	多模态或 Google 生态场景

具体价格、模型名和上下文窗口变化较快，必须以供应商官方 pricing 页面为准。

2.1 MVP 采购/开通清单

项目	要求
供应商账号	至少一个可用于 RAGFlow 的商业模型账号
API key	配置在 RAGFlow 或运行环境 Secret 中
模型用途	至少区分问答、文档迭代、embedding
预算上限	设置月度预算和告警阈值
网络访问	RAGFlow 所在环境能访问模型 API
日志策略	不记录完整敏感 prompt、key 或用户私密数据

3. 如何开发

LLM-WIKI 不直接把模型 SDK 散落在业务代码中，而是定义 ModelProvider 抽象。

class ModelProvider:
    def generate(self, request: GenerateRequest) -> GenerateResult: ...
    def embed(self, request: EmbedRequest) -> EmbedResult: ...

RAGFlow 如果已经内置模型配置，则 LLM-WIKI 只保存模型用途策略，不重复保存模型 key。

4. 如何部署

模型 key 放在：

• RAGFlow 的模型供应商配置中。
• 或 GitHub Actions Secrets / 运行服务环境变量中。

禁止：

• 写入 Git。
• 写入 publish/**。
• 出现在 PR 日志中。

4.1 RAGFlow 侧部署要求

RAGFlow 中必须完成：

• 配置 chat/completion 模型。
• 配置 embedding 模型。
• 为 llm-wiki-approved 和 llm-wiki-working dataset 使用同一套或兼容 embedding 模型。
• 配置 token/用量统计或至少保留供应商侧用量查询方式。
• 验证 RAGFlow 能完成一次带引用问答和一次文档迭代任务。

4.2 LLM-WIKI 侧部署要求

LLM-WIKI 只需要知道模型用途策略，不直接依赖具体模型 SDK。

运行环境变量：

MODEL_PROVIDER=ragflow-managed
MODEL_POLICY_FILE=config/model-policy.yaml

只有当控制面需要直接调用模型时，才增加：

MODEL_API_BASE
MODEL_API_KEY
MODEL_CHAT_MODEL
MODEL_EMBEDDING_MODEL

默认 MVP 不要求控制面直接调用模型。

5. 如何配置

建议 config/model-policy.yaml：

models:
  qa:
    provider: ragflow-managed
    purpose: answer-generation
    requireCitations: true
    defaultEndpointType: openai-compatible
  rewrite:
    provider: ragflow-managed
    purpose: document-iteration
    requireEvidence: true
  embedding:
    provider: ragflow-managed
    purpose: vector-indexing
    consistencyGroup: llm-wiki-ragflow
budget:
  monthlyLimitUsd: 200
  alertThresholdPercent: 80
logging:
  redactSecrets: true
  storeFullPrompts: false

配置约束：

• qa.requireCitations 必须为 true。
• rewrite.requireEvidence 必须为 true。
• 同一个 RAGFlow dataset 生命周期内，embedding 模型不能随意切换；切换时必须重建索引。
• 月度预算和告警阈值必须进入配置或供应商控制台。
• 模型 key 只能在 RAGFlow 或 Secrets 中配置。

6. 如何使用

场景	使用方式
问答	RAGFlow 调用模型生成引用答案
文档迭代	RAGFlow Agent 调用模型生成改写建议
索引	embedding 模型生成向量
批处理	可选低成本模型，降低离线任务成本

7. 验收标准

• 模型 key 不进入 Git。
• 问答必须基于检索上下文，不允许无引用编造。
• 文档迭代必须输出修改理由。
• 能按用途切换模型。
• 能记录模型调用用量或至少保留 RAGFlow 侧用量统计。
• RAGFlow 能使用配置模型完成一次 llm-wiki-approved dataset 问答。
• RAGFlow 能使用配置模型完成一次文档迭代建议输出。
• embedding 模型切换时有重建索引计划或明确禁止切换。

8. 官方资料

• OpenAI API pricing: https://openai.com/api/pricing/
• Anthropic pricing: https://docs.anthropic.com/en/docs/about-claude/pricing
• Gemini API pricing: https://ai.google.dev/gemini-api/docs/pricing