AAS 的 AI 产品开发指南从 LLM 集成模式到生产级加固的完整实战手册【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本文以 AASagentic-awesome-skills仓库中 ai-product 技能 的详细指南 references/detailed-guide.md 为核心骨架完整梳理 AI 产品从原理、集成模式到生产加固的工程化要点。你将掌握结构化输出校验、流式响应、提示词版本化、RAG 混合检索、成本监控、容错降级等六大核心模式并学会识别与规避导致线上事故的十类Sharp Edges危险边缘最终获得一套可直接落地的生产级 LLM 应用工程清单。一、AI 产品工程化的五大核心原则1.1 LLM 是概率系统不是确定性系统LLM 对相同输入可能产生不同输出。因此产品设计必须为方差预留空间在 LLM 输出与业务逻辑之间强制插入校验层schema 校验绝不盲目信任输出对必然发生的边缘情况做兜底设计。错误示范直接JSON.parseLLM 响应并写入数据库。正确示范先按 schema 校验校验失败则回退到人工审核流程。1.2 提示词工程即产品工程提示词应被视为代码来管理版本化、测试、A/B 实验、编写文档。一字之差可能彻底翻转模型行为。提示词应纳入版本控制并配套回归测试禁止在生产中临时手改提示词而无测试支撑。1.3 多数场景用 RAG 而非微调微调成本高、周期慢、难以更新RAG 可以在不重新训练模型的前提下持续注入新知识。先上 RAG只有当 RAG 触及明确天花板时才考虑微调。1.4 为延迟而设计LLM 单次调用耗时 130 秒用户厌恶等待。应对手段流式响应、进度提示、预计算、激进缓存。1.5 成本就是产品特性LLM API 成本随规模急剧上升。应在每次查询级别度量成本、为简单任务选用更小模型、对一切可缓存内容做缓存。补充佐证本仓库将ai-product归类于ai-ml类别见 data/catalog.json其元数据risk: safe、来源为 vibeship-spawner-skillsApache 2.0定位为Every product will be AI-powered与上述原则完全一致。二、六大核心实现模式Patterns2.1 结构化输出 Schema 校验适用场景LLM 输出将被程序化消费分类、提取、路由等。核心做法是启用 JSON 模式或函数调用并用 Zod 等 schema 库做运行时校验import { z } from zod; const schema z.object({ category: z.enum([bug, feature, question]), priority: z.number().min(1).max(5), summary: z.string().max(200) }); const response await openai.chat.completions.create({ model: gpt-4, messages: [{ role: user, content: prompt }], response_format: { type: json_object } }); const parsed schema.parse(JSON.parse(response.content));要点先请求 JSON 输出再JSON.parse最后schema.parse校验——任何一步失败都要进入兜底分支而不是继续向下游传递脏数据。2.2 流式响应 进度反馈适用场景面向用户的聊天或生成类功能。开启stream: true后逐块消费增量内容并推送至客户端const stream await openai.chat.completions.create({ model: gpt-4, messages, stream: true }); for await (const chunk of stream) { const content chunk.choices[0]?.delta?.content; if (content) { yield content; // Stream to client } }流式输出能显著降低感知延迟、让用户保持参与服务端可用OpenAIStreamStreamingTextResponse如 Next.js Vercel AI SDK承接前端用useChat()实时渲染增量 token。2.3 提示词版本化与回归测试适用场景任何进入生产的提示词。将提示词以版本化常量形式存放并内置测试用例在 CI 中回归// prompts/categorize-ticket.ts export const CATEGORIZE_TICKET_V2 { version: 2.0, system: You are a support ticket categorizer..., test_cases: [ { input: Login broken, expected: { category: bug } }, { input: Want dark mode, expected: { category: feature } } ] }; // Test in CI const result await llm.generate(prompt, test_case.input); assert.equal(result.category, test_case.expected.category);2.4 昂贵操作的缓存适用场景相同查询被反复处理如 embedding 计算。// Cache embeddings (expensive to compute) const cacheKey embedding:${hash(text)}; let embedding await cache.get(cacheKey); if (!embedding) { embedding await openai.embeddings.create({ model: text-embedding-3-small, input: text }); await cache.set(cacheKey, embedding, 30d); }2.5 LLM 故障熔断器Circuit Breaker适用场景LLM 集成位于关键路径上。熔断器在连续失败达到阈值后暂停调用避免在服务异常时继续烧钱烧配额const circuitBreaker new CircuitBreaker(callLLM, { threshold: 5, // failures timeout: 30000, // ms resetTimeout: 60000 // ms }); try { const response await circuitBreaker.fire(prompt); return response; } catch (error) { // Fallback: rule-based system, cached response, or human queue return fallbackHandler(prompt); }2.6 RAG 混合检索语义 关键词 重排适用场景实现 RAG 系统。单一向量检索容易漏掉精确关键词命中混合检索先用两种方式各取 top-20再合并重排取 top-5// 1. Semantic search (vector similarity) const embedding await embed(query); const semanticResults await vectorDB.search(embedding, topK: 20); // 2. Keyword search (BM25) const keywordResults await fullTextSearch(query, topK: 20); // 3. Rerank combined results const combined rerank([...semanticResults, ...keywordResults]); const topChunks combined.slice(0, 5); // 4. Add to prompt const context topChunks.map(c c.text).join(\n\n);纵深延伸本仓库的 rag-engineer 技能 与 hybrid-search-implementation 技能 是这一模式的配套实现参考。rag-engineer 明确主张retrieval quality determines generation quality - garbage in, garbage out将 chunking 边界、embedding 维度、相似度度量、重排与过滤策略视为检索质量的核心变量与本文的混合检索步骤形成完整闭环。三、十类 Sharp Edges生产事故的高发地带与修复方案3.1 未校验就信任 LLM 输出CRITICAL症状JSON.parse无 try-catch、无 schema 校验、直接使用 LLM 文本输出、畸形响应导致崩溃。根因LLM 是概率系统迟早产出意外输出把 LLM 响应当可信输入等同于把用户输入当可信输入。修复方案import { z } from zod; const ResponseSchema z.object({ answer: z.string(), confidence: z.number().min(0).max(1), sources: z.array(z.string()).optional(), }); async function queryLLM(prompt: string) { const response await openai.chat.completions.create({ model: gpt-4, messages: [{ role: user, content: prompt }], response_format: { type: json_object }, }); const parsed JSON.parse(response.choices[0].message.content); const validated ResponseSchema.parse(parsed); // Throws if invalid return validated; }更优做法是**使用函数调用function calling**强制模型输出结构化字段并预先设计校验失败时的兜底策略重试默认值人工审核。3.2 未经消毒的用户输入直入提示词CRITICAL症状提示词中模板字符串内插用户输入、无长度限制、用户可改变模型行为。根因LLM 会执行指令用户输入进入提示词相当于针对 AI 的 SQL 注入攻击者可能劫持模型行为。四层防御分离用户输入——用独立 message 承载避免拼接进 system prompt// BAD - injection possible const prompt Analyze this text: ${userInput}; // BETTER - clear separation const messages [ { role: system, content: You analyze text for sentiment. }, { role: user, content: userInput }, // Separate message ];输入消毒——限制长度、剥离控制字符、检测提示注入模式输出过滤——检查系统提示词泄漏、按期望模式校验输出最小权限——LLM 不应具备危险能力限制工具访问范围。3.3 上下文窗口塞入过多内容HIGH症状token 超限报错、响应被静默截断、所有检索块全量塞入、无 token 计数。根因上下文窗口有限超量导致报错或截断上下文越多不一定越好噪声会淹没信号。发送前先计算 tokenimport { encoding_for_model } from tiktoken; const enc encoding_for_model(gpt-4); function countTokens(text: string): number { return enc.encode(text).length; } function buildPrompt(chunks: string[], maxTokens: number) { let totalTokens 0; const selected []; for (const chunk of chunks) { const tokens countTokens(chunk); if (totalTokens tokens maxTokens) break; selected.push(chunk); totalTokens tokens; } return selected.join(\n\n); }配套策略按相关性排序取 top-k、过长则先摘要、长文档用滑动窗口、为响应预留 token 额度。3.4 等待完整响应后才展示HIGH症状长时间 spinner、stream: false、只处理完整响应。根因LLM 响应耗时数秒等待完整响应给用户卡死的错觉。修复服务端流式返回 前端增量渲染// Next.js Vercel AI SDK import { OpenAIStream, StreamingTextResponse } from ai; export async function POST(req: Request) { const { messages } await req.json(); const response await openai.chat.completions.create({ model: gpt-4, messages, stream: true, }); const stream OpenAIStream(response); return new StreamingTextResponse(stream); }前端const { messages, isLoading } useChat();即可让消息随 token 到达实时刷新。结构化输出场景可先流式思考过程再解析最终 JSON或展示骨架屏后流入内容。3.5 不监控 LLM API 成本HIGH症状不记录usage.tokens、无按用户追踪、账单突袭、无按用户限流。根因LLM 成本累积极快如 GPT-4 约 $30-60/百万 token无追踪只能等账单上门规模化后可能危及生存。修复按请求落库 设限 优化async function queryWithCostTracking(prompt: string, userId: string) { const response await openai.chat.completions.create({...}); const usage response.usage; await db.llmUsage.create({ userId, model: gpt-4, inputTokens: usage.prompt_tokens, outputTokens: usage.completion_tokens, cost: calculateCost(usage), timestamp: new Date(), }); return response; }配套按用户每日/每月限额、告警阈值、用量看板优化方向包括更便宜模型、常见查询缓存、更短提示词。3.6 LLM API 故障导致应用整体宕机HIGH症状单一 LLM 供应商、API 调用无 try-catch、失败即报错页、无缓存响应。根因LLM API 会失败、会被限流、会宕机不做降级设计你的可用性就绑定在供应商的可用性上。纵深防御async function queryWithFallback(prompt: string) { try { return await queryOpenAI(prompt); } catch (error) { if (isRateLimitError(error)) { return await queryAnthropic(prompt); // Fallback provider } if (isTimeoutError(error)) { return await getCachedResponse(prompt); // Cache fallback } return getDefaultResponse(); // Graceful degradation } }配套策略多供应商如 OpenAI Anthropic、常见查询响应缓存、优雅降级 UI、非紧急请求入队重试熔断器在连续 N 次失败后暂停尝试 X 分钟避免在故障服务上继续消耗配额。3.7 不校验 LLM 输出中的事实CRITICAL症状无来源引用、无置信度指示、未经验证的事实性陈述、用户投诉错误信息。根因LLM 会幻觉且错误时语气同样自信用户难以分辨在医疗、法律、金融等高危领域尤其危险。修复RAG 来源验证 显式不确定性const response await generateWithSources(query); // Verify each cited source exists for (const source of response.sources) { const exists await verifySourceExists(source); if (!exists) { response.sources response.sources.filter(s s ! source); response.confidence low; } }并向用户展示置信度、不确定时明说我不确定、附上可核验的来源链接高危答案须对照权威来源交叉校验或引入人工审核。3.8 在同步请求处理器中调用 LLMHIGH症状LLM 功能请求超时、处理器内阻塞式 await、LLM 任务无任务队列。根因LLM 调用慢130 秒在请求处理器中阻塞会导致超时、体验差和扩展性问题。异步方案流式聊天首选边生成边响应任务队列处理类首选app.post(/process, async (req, res) { const jobId await queue.add(llm-process, { input: req.body }); res.json({ jobId, status: processing }); }); // Separate worker processes jobs // Client polls or uses WebSocket for result乐观 UI立即返回占位结果完成后再推送更新Serverless 考量边缘函数超时通常 30 秒长任务需后台处理。3.9 生产环境无版本控制地改提示词HIGH症状提示词内联在代码中、无 git 历史、无法复现旧行为、无 A/B 测试设施。根因提示词即代码改动影响行为不版本化就无法追踪变更、回滚问题或 A/B 测试。修复将提示词作为代码管理——目录化存储如/prompts/chat-assistant/v1.yaml、/v2.yaml或用 Langfuse、PromptLayer、Helicone 等提示词管理平台也可在数据库按版本管理并启用当前版本const prompt await db.prompts.findFirst({ where: { name: chat-assistant, isActive: true }, orderBy: { version: desc }, });A/B 测试时随机分配用户到不同版本并分版本统计指标。3.10 微调先行未穷尽 RAG 与提示词MEDIUM症状为让模型了解公司直接微调未先尝试 RAG抱怨 RAG 性能却不做优化。根因微调昂贵、迭代慢、难更新RAG 优质提示词可解决约 90% 的知识类问题。按顺序尝试更优提示词few-shot 示例、更清晰的指令、输出格式说明RAG文档检索、知识库集成、实时更新微调最后手段需要特定语气/风格、上下文窗口不足、延迟敏感更小的微调模型。微调前置条件100 高质量示例、清晰的评估指标、足够的迭代预算。四、可编程校验检查清单Validation Checks本指南还提供了一组可直接接入 CI 或代码评审的检查项按严重级别划分严重级别检查项检查要点ERRORLLM API key 硬编码密钥应来自环境变量WARNINGLLM 输出未校验用 Zod 等做 schema 校验WARNING未消毒用户输入进入提示词消毒或改用独立 messageWARNINGLLM 调用无错误处理增加 try-catchWARNINGLLM 调用无超时防止请求挂起WARNING用户向 LLM 端点无限流增加按用户限额INFOLLM 响应未流式长响应建议stream: trueINFO无 token 用量追踪记录 token 用于成本监控INFO顺序生成 embedding批量请求提升性能INFO单一 LLM 供应商无后备考虑备份供应商应对故障纵深延伸本仓库的 llm-evaluation 技能 可为本清单提供评估方法论支撑llm-prompt-optimizer 技能 与 prompt-engineering-patterns 技能 则覆盖提示词层面的系统化优化与校验与本文的提示词版本化、A/B 测试、回归测试形成互补。五、跨角色协作与 AI 功能落地流程Collaboration5.1 委派触发规则Delegation Triggers当任务触及以下关键词时应委派给对应专业角色触发关键词委派角色原因backend、api、server、database后端AI 需要后端实现ui、component、streaming、chat前端AI 需要前端实现cost、billing、usage、optimizeDevOpsAI 成本需要监控security、pii、data protection安全AI 处理敏感数据5.2 AI 功能开发流程涉及技能ai-product、backend、frontend、qa-engineering。1. AI architecture (ai-product) 2. Backend integration (backend) 3. Frontend implementation (frontend) 4. Testing and validation (qa-engineering)5.3 RAG 落地流程涉及技能ai-product、backend、analytics-architecture。1. RAG design (ai-product) 2. Vector storage (backend) 3. Retrieval optimization (ai-product) 4. Usage analytics (analytics-architecture)六、如何使用本技能使用前提与限制在 AAS 仓库中ai-product技能入口文件为 SKILL.md本文对应的完整参考材料位于 references/detailed-guide.md。仓库同时收录了同源的 skills/ai-product 目录版本目录元数据risk: safe、分类ai-ml可在 data/catalog.json 与 skills_index.json 中核验。使用原则当请求明显匹配上述能力与模式时使用本技能仅限任务明确处于该范围时使用输出不能替代环境特定的验证、测试与专家评审当输入、权限、安全边界或成功标准缺失时应停下并请求澄清。这一约束同样适用于本文给出的所有代码模式——它们是可复制的工程模板但上线前仍须经过与你实际环境模型版本、供应商、数据规模匹配的验证。结语从能跑通的 Demo到不散架的生产系统AI 产品工程的本质是在承认 LLM 概率性、延迟、成本与幻觉风险的前提下用工程手段把不确定性关进笼子里。本文以 AAS 仓库的 ai-product 详细指南为主线覆盖了五大原则、六大模式、十类高危边缘场景与十项可编程校验检查。把本文中的 schema 校验、流式响应、提示词版本化、混合检索、成本追踪与多级降级逐条落到你的代码库你就拥有了把 AI 功能从演示可用推向生产可用的完整工具箱。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/20 11:10:56 · 阅读 1.2k AAS 的 AI 产品开发指南：从 LLM 集成模式到生产级加固的完整实战手册
AAS 的 AI 产品开发指南从 LLM 集成模式到生产级加固的完整实战手册【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读本文以 AASagentic-awesome-skills仓库中 ai-product 技能 的详细指南 references/detailed-guide.md 为核心骨架完整梳理 AI 产品从原理、集成模式到生产加固的工程化要点。你将掌握结构化输出校验、流式响应、提示词版本化、RAG 混合检索、成本监控、容错降级等六大核心模式并学会识别与规避导致线上事故的十类Sharp Edges危险边缘最终获得一套可直接落地的生产级 LLM 应用工程清单。一、AI 产品工程化的五大核心原则1.1 LLM 是概率系统不是确定性系统LLM 对相同输入可能产生不同输出。因此产品设计必须为方差预留空间在 LLM 输出与业务逻辑之间强制插入校验层schema 校验绝不盲目信任输出对必然发生的边缘情况做兜底设计。错误示范直接JSON.parseLLM 响应并写入数据库。正确示范先按 schema 校验校验失败则回退到人工审核流程。1.2 提示词工程即产品工程提示词应被视为代码来管理版本化、测试、A/B 实验、编写文档。一字之差可能彻底翻转模型行为。提示词应纳入版本控制并配套回归测试禁止在生产中临时手改提示词而无测试支撑。1.3 多数场景用 RAG 而非微调微调成本高、周期慢、难以更新RAG 可以在不重新训练模型的前提下持续注入新知识。先上 RAG只有当 RAG 触及明确天花板时才考虑微调。1.4 为延迟而设计LLM 单次调用耗时 130 秒用户厌恶等待。应对手段流式响应、进度提示、预计算、激进缓存。1.5 成本就是产品特性LLM API 成本随规模急剧上升。应在每次查询级别度量成本、为简单任务选用更小模型、对一切可缓存内容做缓存。补充佐证本仓库将ai-product归类于ai-ml类别见 data/catalog.json其元数据risk: safe、来源为 vibeship-spawner-skillsApache 2.0定位为Every product will be AI-powered与上述原则完全一致。二、六大核心实现模式Patterns2.1 结构化输出 Schema 校验适用场景LLM 输出将被程序化消费分类、提取、路由等。核心做法是启用 JSON 模式或函数调用并用 Zod 等 schema 库做运行时校验import { z } from zod; const schema z.object({ category: z.enum([bug, feature, question]), priority: z.number().min(1).max(5), summary: z.string().max(200) }); const response await openai.chat.completions.create({ model: gpt-4, messages: [{ role: user, content: prompt }], response_format: { type: json_object } }); const parsed schema.parse(JSON.parse(response.content));要点先请求 JSON 输出再JSON.parse最后schema.parse校验——任何一步失败都要进入兜底分支而不是继续向下游传递脏数据。2.2 流式响应 进度反馈适用场景面向用户的聊天或生成类功能。开启stream: true后逐块消费增量内容并推送至客户端const stream await openai.chat.completions.create({ model: gpt-4, messages, stream: true }); for await (const chunk of stream) { const content chunk.choices[0]?.delta?.content; if (content) { yield content; // Stream to client } }流式输出能显著降低感知延迟、让用户保持参与服务端可用OpenAIStreamStreamingTextResponse如 Next.js Vercel AI SDK承接前端用useChat()实时渲染增量 token。2.3 提示词版本化与回归测试适用场景任何进入生产的提示词。将提示词以版本化常量形式存放并内置测试用例在 CI 中回归// prompts/categorize-ticket.ts export const CATEGORIZE_TICKET_V2 { version: 2.0, system: You are a support ticket categorizer..., test_cases: [ { input: Login broken, expected: { category: bug } }, { input: Want dark mode, expected: { category: feature } } ] }; // Test in CI const result await llm.generate(prompt, test_case.input); assert.equal(result.category, test_case.expected.category);2.4 昂贵操作的缓存适用场景相同查询被反复处理如 embedding 计算。// Cache embeddings (expensive to compute) const cacheKey embedding:${hash(text)}; let embedding await cache.get(cacheKey); if (!embedding) { embedding await openai.embeddings.create({ model: text-embedding-3-small, input: text }); await cache.set(cacheKey, embedding, 30d); }2.5 LLM 故障熔断器Circuit Breaker适用场景LLM 集成位于关键路径上。熔断器在连续失败达到阈值后暂停调用避免在服务异常时继续烧钱烧配额const circuitBreaker new CircuitBreaker(callLLM, { threshold: 5, // failures timeout: 30000, // ms resetTimeout: 60000 // ms }); try { const response await circuitBreaker.fire(prompt); return response; } catch (error) { // Fallback: rule-based system, cached response, or human queue return fallbackHandler(prompt); }2.6 RAG 混合检索语义 关键词 重排适用场景实现 RAG 系统。单一向量检索容易漏掉精确关键词命中混合检索先用两种方式各取 top-20再合并重排取 top-5// 1. Semantic search (vector similarity) const embedding await embed(query); const semanticResults await vectorDB.search(embedding, topK: 20); // 2. Keyword search (BM25) const keywordResults await fullTextSearch(query, topK: 20); // 3. Rerank combined results const combined rerank([...semanticResults, ...keywordResults]); const topChunks combined.slice(0, 5); // 4. Add to prompt const context topChunks.map(c c.text).join(\n\n);纵深延伸本仓库的 rag-engineer 技能 与 hybrid-search-implementation 技能 是这一模式的配套实现参考。rag-engineer 明确主张retrieval quality determines generation quality - garbage in, garbage out将 chunking 边界、embedding 维度、相似度度量、重排与过滤策略视为检索质量的核心变量与本文的混合检索步骤形成完整闭环。三、十类 Sharp Edges生产事故的高发地带与修复方案3.1 未校验就信任 LLM 输出CRITICAL症状JSON.parse无 try-catch、无 schema 校验、直接使用 LLM 文本输出、畸形响应导致崩溃。根因LLM 是概率系统迟早产出意外输出把 LLM 响应当可信输入等同于把用户输入当可信输入。修复方案import { z } from zod; const ResponseSchema z.object({ answer: z.string(), confidence: z.number().min(0).max(1), sources: z.array(z.string()).optional(), }); async function queryLLM(prompt: string) { const response await openai.chat.completions.create({ model: gpt-4, messages: [{ role: user, content: prompt }], response_format: { type: json_object }, }); const parsed JSON.parse(response.choices[0].message.content); const validated ResponseSchema.parse(parsed); // Throws if invalid return validated; }更优做法是**使用函数调用function calling**强制模型输出结构化字段并预先设计校验失败时的兜底策略重试默认值人工审核。3.2 未经消毒的用户输入直入提示词CRITICAL症状提示词中模板字符串内插用户输入、无长度限制、用户可改变模型行为。根因LLM 会执行指令用户输入进入提示词相当于针对 AI 的 SQL 注入攻击者可能劫持模型行为。四层防御分离用户输入——用独立 message 承载避免拼接进 system prompt// BAD - injection possible const prompt Analyze this text: ${userInput}; // BETTER - clear separation const messages [ { role: system, content: You analyze text for sentiment. }, { role: user, content: userInput }, // Separate message ];输入消毒——限制长度、剥离控制字符、检测提示注入模式输出过滤——检查系统提示词泄漏、按期望模式校验输出最小权限——LLM 不应具备危险能力限制工具访问范围。3.3 上下文窗口塞入过多内容HIGH症状token 超限报错、响应被静默截断、所有检索块全量塞入、无 token 计数。根因上下文窗口有限超量导致报错或截断上下文越多不一定越好噪声会淹没信号。发送前先计算 tokenimport { encoding_for_model } from tiktoken; const enc encoding_for_model(gpt-4); function countTokens(text: string): number { return enc.encode(text).length; } function buildPrompt(chunks: string[], maxTokens: number) { let totalTokens 0; const selected []; for (const chunk of chunks) { const tokens countTokens(chunk); if (totalTokens tokens maxTokens) break; selected.push(chunk); totalTokens tokens; } return selected.join(\n\n); }配套策略按相关性排序取 top-k、过长则先摘要、长文档用滑动窗口、为响应预留 token 额度。3.4 等待完整响应后才展示HIGH症状长时间 spinner、stream: false、只处理完整响应。根因LLM 响应耗时数秒等待完整响应给用户卡死的错觉。修复服务端流式返回 前端增量渲染// Next.js Vercel AI SDK import { OpenAIStream, StreamingTextResponse } from ai; export async function POST(req: Request) { const { messages } await req.json(); const response await openai.chat.completions.create({ model: gpt-4, messages, stream: true, }); const stream OpenAIStream(response); return new StreamingTextResponse(stream); }前端const { messages, isLoading } useChat();即可让消息随 token 到达实时刷新。结构化输出场景可先流式思考过程再解析最终 JSON或展示骨架屏后流入内容。3.5 不监控 LLM API 成本HIGH症状不记录usage.tokens、无按用户追踪、账单突袭、无按用户限流。根因LLM 成本累积极快如 GPT-4 约 $30-60/百万 token无追踪只能等账单上门规模化后可能危及生存。修复按请求落库 设限 优化async function queryWithCostTracking(prompt: string, userId: string) { const response await openai.chat.completions.create({...}); const usage response.usage; await db.llmUsage.create({ userId, model: gpt-4, inputTokens: usage.prompt_tokens, outputTokens: usage.completion_tokens, cost: calculateCost(usage), timestamp: new Date(), }); return response; }配套按用户每日/每月限额、告警阈值、用量看板优化方向包括更便宜模型、常见查询缓存、更短提示词。3.6 LLM API 故障导致应用整体宕机HIGH症状单一 LLM 供应商、API 调用无 try-catch、失败即报错页、无缓存响应。根因LLM API 会失败、会被限流、会宕机不做降级设计你的可用性就绑定在供应商的可用性上。纵深防御async function queryWithFallback(prompt: string) { try { return await queryOpenAI(prompt); } catch (error) { if (isRateLimitError(error)) { return await queryAnthropic(prompt); // Fallback provider } if (isTimeoutError(error)) { return await getCachedResponse(prompt); // Cache fallback } return getDefaultResponse(); // Graceful degradation } }配套策略多供应商如 OpenAI Anthropic、常见查询响应缓存、优雅降级 UI、非紧急请求入队重试熔断器在连续 N 次失败后暂停尝试 X 分钟避免在故障服务上继续消耗配额。3.7 不校验 LLM 输出中的事实CRITICAL症状无来源引用、无置信度指示、未经验证的事实性陈述、用户投诉错误信息。根因LLM 会幻觉且错误时语气同样自信用户难以分辨在医疗、法律、金融等高危领域尤其危险。修复RAG 来源验证 显式不确定性const response await generateWithSources(query); // Verify each cited source exists for (const source of response.sources) { const exists await verifySourceExists(source); if (!exists) { response.sources response.sources.filter(s s ! source); response.confidence low; } }并向用户展示置信度、不确定时明说我不确定、附上可核验的来源链接高危答案须对照权威来源交叉校验或引入人工审核。3.8 在同步请求处理器中调用 LLMHIGH症状LLM 功能请求超时、处理器内阻塞式 await、LLM 任务无任务队列。根因LLM 调用慢130 秒在请求处理器中阻塞会导致超时、体验差和扩展性问题。异步方案流式聊天首选边生成边响应任务队列处理类首选app.post(/process, async (req, res) { const jobId await queue.add(llm-process, { input: req.body }); res.json({ jobId, status: processing }); }); // Separate worker processes jobs // Client polls or uses WebSocket for result乐观 UI立即返回占位结果完成后再推送更新Serverless 考量边缘函数超时通常 30 秒长任务需后台处理。3.9 生产环境无版本控制地改提示词HIGH症状提示词内联在代码中、无 git 历史、无法复现旧行为、无 A/B 测试设施。根因提示词即代码改动影响行为不版本化就无法追踪变更、回滚问题或 A/B 测试。修复将提示词作为代码管理——目录化存储如/prompts/chat-assistant/v1.yaml、/v2.yaml或用 Langfuse、PromptLayer、Helicone 等提示词管理平台也可在数据库按版本管理并启用当前版本const prompt await db.prompts.findFirst({ where: { name: chat-assistant, isActive: true }, orderBy: { version: desc }, });A/B 测试时随机分配用户到不同版本并分版本统计指标。3.10 微调先行未穷尽 RAG 与提示词MEDIUM症状为让模型了解公司直接微调未先尝试 RAG抱怨 RAG 性能却不做优化。根因微调昂贵、迭代慢、难更新RAG 优质提示词可解决约 90% 的知识类问题。按顺序尝试更优提示词few-shot 示例、更清晰的指令、输出格式说明RAG文档检索、知识库集成、实时更新微调最后手段需要特定语气/风格、上下文窗口不足、延迟敏感更小的微调模型。微调前置条件100 高质量示例、清晰的评估指标、足够的迭代预算。四、可编程校验检查清单Validation Checks本指南还提供了一组可直接接入 CI 或代码评审的检查项按严重级别划分严重级别检查项检查要点ERRORLLM API key 硬编码密钥应来自环境变量WARNINGLLM 输出未校验用 Zod 等做 schema 校验WARNING未消毒用户输入进入提示词消毒或改用独立 messageWARNINGLLM 调用无错误处理增加 try-catchWARNINGLLM 调用无超时防止请求挂起WARNING用户向 LLM 端点无限流增加按用户限额INFOLLM 响应未流式长响应建议stream: trueINFO无 token 用量追踪记录 token 用于成本监控INFO顺序生成 embedding批量请求提升性能INFO单一 LLM 供应商无后备考虑备份供应商应对故障纵深延伸本仓库的 llm-evaluation 技能 可为本清单提供评估方法论支撑llm-prompt-optimizer 技能 与 prompt-engineering-patterns 技能 则覆盖提示词层面的系统化优化与校验与本文的提示词版本化、A/B 测试、回归测试形成互补。五、跨角色协作与 AI 功能落地流程Collaboration5.1 委派触发规则Delegation Triggers当任务触及以下关键词时应委派给对应专业角色触发关键词委派角色原因backend、api、server、database后端AI 需要后端实现ui、component、streaming、chat前端AI 需要前端实现cost、billing、usage、optimizeDevOpsAI 成本需要监控security、pii、data protection安全AI 处理敏感数据5.2 AI 功能开发流程涉及技能ai-product、backend、frontend、qa-engineering。1. AI architecture (ai-product) 2. Backend integration (backend) 3. Frontend implementation (frontend) 4. Testing and validation (qa-engineering)5.3 RAG 落地流程涉及技能ai-product、backend、analytics-architecture。1. RAG design (ai-product) 2. Vector storage (backend) 3. Retrieval optimization (ai-product) 4. Usage analytics (analytics-architecture)六、如何使用本技能使用前提与限制在 AAS 仓库中ai-product技能入口文件为 SKILL.md本文对应的完整参考材料位于 references/detailed-guide.md。仓库同时收录了同源的 skills/ai-product 目录版本目录元数据risk: safe、分类ai-ml可在 data/catalog.json 与 skills_index.json 中核验。使用原则当请求明显匹配上述能力与模式时使用本技能仅限任务明确处于该范围时使用输出不能替代环境特定的验证、测试与专家评审当输入、权限、安全边界或成功标准缺失时应停下并请求澄清。这一约束同样适用于本文给出的所有代码模式——它们是可复制的工程模板但上线前仍须经过与你实际环境模型版本、供应商、数据规模匹配的验证。结语从能跑通的 Demo到不散架的生产系统AI 产品工程的本质是在承认 LLM 概率性、延迟、成本与幻觉风险的前提下用工程手段把不确定性关进笼子里。本文以 AAS 仓库的 ai-product 详细指南为主线覆盖了五大原则、六大模式、十类高危边缘场景与十项可编程校验检查。把本文中的 schema 校验、流式响应、提示词版本化、混合检索、成本追踪与多级降级逐条落到你的代码库你就拥有了把 AI 功能从演示可用推向生产可用的完整工具箱。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考