阿里百炼（BaiLian）AI 接入教程（通用版）

AI前沿
1

阿里百炼（BaiLian）AI 接入教程（通用版）

适用场景：后端服务需要调用阿里百炼大模型完成文本生成/总结/问答/结构化抽取等任务，并将“发送内容与AI回复”按需落库。本文按通用代码形态整理，可直接映射到你现有的 ApiKey 检查、systemPrompt、创建服务、拼接最终提示词、调用 ChatWithHistoryAsync、落库与日志流程。

1. 总体流程概览（与代码结构对齐）

典型调用链路可拆为 4 步：

  1. 读取百炼配置（ApiKey/ModelName/SystemPrompt）
  • 若 ApiKey 为空：记录日志并跳过 AI 调用（业务可降级为规则/默认文案/不生成）。
  1. 准备输入数据（业务侧）

  • 从业务对象/数据包/数据库中抽取“本次需要模型处理的内容”。

  • 对长文本做截断/摘要（必要时分段，多次调用也需保持一致策略）。

  1. 构造最终提示词（Prompt）

  • systemPrompt：定义角色、边界、风格与禁区（例如“只基于提供内容，不要编造”）。

  • responseFormatHint：定义输出格式（Markdown 结构或 JSON 结构），并要求严格遵守。

  • 将多个子问题/多段文本合并成一次请求，保证一致性并降低调用次数。

  1. 调用百炼并保存结果

  • CreateChatHistory(systemPrompt) 创建上下文。

  • ChatWithHistoryAsync(chatHistory, finalPrompt) 发起对话。

  • 将发送内容与 AI 回复按需落库。

2. 百炼配置说明（Config / BaiLianConfig）

建议配置项：

  • ApiKey：百炼 API 密钥（必须保密）

  • ModelName：模型名称（对话模型/指令模型等）

  • SystemPrompt：系统提示词（可空；为空时使用默认通用系统提示）

推荐默认系统提示词（通用版）：

  • “你是一名专业的企业应用助手。请严格基于用户提供的内容回答，不要编造未提供的信息；如信息不足，请说明缺失点并提出需要的补充信息。输出遵循我给定的格式要求。”

配置与密钥建议：

  • 不要把 ApiKey 写进代码仓库。

  • 优先使用环境变量、配置中心加密、KMS/KeyVault 等托管密钥。

  • 生产环境对读取密钥与相关配置的权限做最小化。

3. 输入数据准备（通用）

3.1 输入来源

常见输入来源包括：

  • 前端提交的表单/富文本

  • 设备/第三方系统回传的内容

  • 业务数据库中的记录（工单、日志、评论、对话、文档片段）

  • 多条子任务（多个问题、多段文本、多条记录）

3.2 输入组织建议

  • 只保留与任务相关的字段与片段。

  • 为每段输入加上清晰标题/编号，便于模型引用。

  • 明确任务目标：生成、总结、对比、抽取、改写、分类等。

4. Prompt 构造：多段合并 + 输出格式约束

4.1 为什么合并多段/多问题

把多个子问题或多段原文合并成一次请求的收益：

  • 避免多次调用导致答案风格/结论不一致

  • 降低请求次数与成本

  • 让模型在更完整上下文内推理（更少误解）

合并策略建议：

  • 固定顺序（如 Question1..N 或 Section1..N）

  • 每段之间用空行或分隔符清晰分隔

  • 对每段加“标题/编号”，方便模型引用

4.2 systemPrompt 与 responseFormatHint 的分工

  • systemPrompt：定义角色、语气、边界（例如“只基于提供内容，不要编造”）

  • responseFormatHint：定义输出结构（强约束），例如：

  • Markdown 结构：适合直接展示

  • JSON 结构：适合程序解析、入库与前端渲染

4.3 推荐：只返回 JSON（更稳定、更易验收）

如需强一致、可校验、可解析，建议使用 JSON 输出约束，并在服务端做：

  • JSON 解析校验（失败则重试或降级）

  • 字段缺失检查

  • 字段长度/数组长度限制

JSON 输出示例（仅示意，按你业务字段调整）：

  • { "Summary": "...", "KeyPoints": ["..."], "Risks": ["..."], "Actions": ["..."] }

5. 日志与错误处理建议

建议生产环境遵循：

  • 不打印完整 Prompt 与完整 Reply（避免日志膨胀与信息泄露风险）。

  • 只记录必要的诊断信息：

  • 请求ID（随机UUID）

  • 模型名、耗时、成功/失败、错误码

  • 入参长度/摘要哈希（不要记录密钥与凭证）

异常与降级策略建议：

  • 超时控制 + 重试（指数退避）

  • 熔断/限流保护

  • 失败时返回可解释的降级结果（规则建议/空内容/提示补充信息）

6. 落库字段建议（SendContent / AiContent）

推荐最小落库集合：

  • SendContent：最终输入（便于复现与审计）

  • AiContent：模型回复

  • ModelName / 调用耗时 / 调用时间 / 请求ID

存储建议：

  • 对 SendContent/AiContent 做访问控制（按角色/租户）。

  • 为数据设定保留期与删除策略。

7. 可复用提示词模板（通用版）

7.1 通用 systemPrompt（示例）

  • “你是企业应用助手。仅基于我提供的内容回答；不要编造；若信息不足请列出缺失点；输出严格遵循格式要求。”

7.2 通用 responseFormatHint（示例：JSON）

  • “请只返回 JSON（不要 Markdown/代码块/多余解释），格式：{…}。字段缺失用空字符串或空数组，不要添加未声明字段。”

8. 常见问题（排查清单）

8.1 提示“未配置 API 密钥”

  • 检查 ApiKey 是否为空/空白

  • 检查配置加载来源与权限（环境变量/配置中心/密钥服务）

8.2 AI 返回为空或不稳定

  • 输入是否为空或过短

  • 是否触发限流/超时

  • 输出格式约束是否过弱（建议改为只返回 JSON 并做校验）

8.3 JSON 解析失败

  • 提示词是否明确“只返回 JSON”

  • 是否包含多余前后缀文本

  • 服务端应对失败做重试/纠错/降级

9. 最佳实践小结（可直接作为团队规范）

  • 密钥不入库不入日志：不要在任何日志或错误信息中输出 ApiKey/Token。

  • 输入可控：长文本做截断/摘要，避免一次请求过大。

  • 输出可校验：优先 JSON；解析失败要有重试与降级。

  • 可观测性：记录请求ID、耗时、错误码，便于定位问题。

  • 可回放：按需保存输入与输出，方便追溯与质量评估。