llm

LLM 实现指南

目录结构

与 LLM 相关的代码按特定目录组织：

• apps/web/utils/ai/ - 主要的 LLM 实现
• apps/web/utils/llms/ - 核心 LLM 工具和配置
• apps/web/__tests__/ - LLM 专用测试

关键文件

• utils/llms/index.ts - 核心 LLM 功能
• utils/llms/model.ts - 模型定义和配置
• utils/usage.ts - 使用情况跟踪和监控

实现模式

请遵循以下标准结构编写与 LLM 相关的函数：

import { z } from "zod";
import { createScopedLogger } from "@/utils/logger";
import { chatCompletionObject } from "@/utils/llms";
import type { EmailAccountWithAI } from "@/utils/llms/types";
import { createGenerateObject } from "@/utils/llms";

export async function featureFunction(options: {
  inputData: InputType;
  emailAccount: EmailAccountWithAI;
}) {
  const { inputData, user } = options;

  if (!inputData || [other validation conditions]) {
    logger.warn("Invalid input for feature function");
    return null;
  }

  const system = `[Detailed system prompt that defines the LLM's role and task]`;

  const prompt = `[User prompt with context and specific instructions]

<data>
...
</data>

${emailAccount.about ? `<user_info>${emailAccount.about}</user_info>` : ""}`;

  const modelOptions = getModel(emailAccount.user);

  const generateObject = createGenerateObject({
    userEmail: emailAccount.email,
    label: "Feature Name",
    modelOptions,
  });


  const result = await generateObject({
    ...modelOptions,
    system,
    prompt,
    schema: z.object({
      field1: z.string(),
      field2: z.number(),
      nested: z.object({
        subfield: z.string(),
      }),
      array_field: z.array(z.string()),
    }),
  });

  return result.object;
}

最佳实践

1. 系统提示词和用户提示词：

   • 将系统提示词和用户提示词分开
   • 系统提示词应定义 LLM 的角色和任务规范
   • 用户提示词应包含实际数据和上下文

2. 模式验证：

   • 始终定义 Zod 模式来验证响应
   • 尽可能具体地定义模式，以引导 LLM 的输出

3. 日志记录：

   • 为每个功能使用描述性、作用域明确的日志记录器
   • 使用适当的日志级别记录输入和输出
   • 在日志消息中包含相关上下文

4. 错误处理：

   • 对无效输入尽早返回
   • 使用恰当的错误类型并记录日志
   • 为 AI 失败实现回退机制
   • 使用 withRetry 为瞬时故障添加重试逻辑

5. 输入格式化：

   • 使用类似 XML 的标签组织提示词中的数据
   • 删除多余空白并截断过长的输入
   • 在相似函数之间统一数据格式

6. 类型安全：

   • 为所有参数和返回值使用 TypeScript 类型
   • 为复杂的输入／输出结构定义清晰的接口

7. 代码组织：

   • 将相关的 AI 函数放在同一文件或目录中
   • 将常见模式提取为工具函数
   • 使用清晰的注释说明复杂的 AI 逻辑

8. AI 优先行为：

   • 优先使用通用的提示词指令、结构化输出和模型选择，而不是模仿模型推理的脆弱词汇启发式方法
   • 只有当产品确实需要模型之外的硬性规则时，才添加确定性过滤器
   • 不要仅为通过测试而添加与评估样例高度相似的提示词示例

9. 草稿归因版本管理：

   • 更改草稿生成的提示词输入、检索上下文、路由或后处理时，递增 apps/web/utils/ai/reply/draft-attribution.ts 中的 DRAFT_PIPELINE_VERSION
   • 将该版本视为用于比较回复草稿质量的分析归因版本

测试

请参阅 llm-test.mdc