SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场managing-llm-prompts

managing-llm-prompts

智能体与模型

查看项目

更新于 11-12 15:23

技能介绍

用途

该技能用于借助 PostHog 的提示词管理（prompt management）功能，创建、版本化、发布并接入 LLM 提示词。PostHog 将提示词以不可变版本存储，应用在运行时拉取，因此修改提示词无需重新部署。

需要明确的一点：提示词存在于 PostHog 但没有任何代码拉取它，对用户而言没有任何变化。只有当应用真正拉取了该提示词，或用户明确表示会自行接入时，任务才算完成。如果只创建了提示词，应明确告知用户应用尚未使用它，并主动提出可以帮忙接入。

主要能力

  • 从代码中迁移硬编码的提示词字符串到 PostHog。
  • 新建提示词，并接入将使用它的代码。
  • 修改 PostHog 中已存在的提示词，生成新版本。
  • 通过标签（label）控制发布：标签是指向某个版本的指针，代码按标签拉取时，只有标签移动才会拿到新版本。
  • 在 Python（posthog）和 Node（@posthog/ai 配合 posthog-node）中接入 SDK 拉取提示词。
  • 验证拉取是否真正生效，避免因回退（fallback）掩盖失败。

使用方式

起点判断

  • 代码中硬编码的提示词：找出应用发送给模型的提示词字符串，迁移用户指定的那些；若用户未指定，列出找到的内容并询问要迁移哪些。
  • 新提示词：创建后接入将使用它的代码。
  • PostHog 中已存在的提示词：进入“修改已有提示词”流程。

无论哪种情况，都应先调用 posthog:llma-prompt-list，因为可能已存在用途相同的提示词，且名称必须唯一。

创建提示词

使用 posthog:llma-prompt-create。名称允许字母、数字、连字符和下划线，new 为保留名。名称创建后不可更改，代码通过名称引用提示词，应选择能描述用途的名称，例如 support-reply-system。

运行时值写成 {{variable}}。从代码迁移时，把每个 f-string 字段或模板字面量占位符转换为该形式，并保留变量名。compile 只做值替换；诸如 {amount:.2f} 的格式说明或 ${items.length} 这类表达式仍留在应用代码中，由代码把结果作为普通变量传入。

当用户希望无需部署即可修改模型设置（model、temperature、工具定义）时，将其放入 config，config 与提示词一同版本化。

迁移时逐字复制提示词文本，不要在同一步骤中改进措辞。第一个版本的行为必须与硬编码版本一致。

用标签发布

发布版本与释放（release）是两个独立步骤。标签是指向某个版本的指针，按标签拉取的代码只有在标签移动时才会拿到新版本。

创建提示词后，调用 posthog:llma-prompt-label-set 将 production 指向版本 1。代码应以 label='production' 拉取。后续版本在有人移动标签前不会进入生产环境。

不带标签或版本拉取的代码会拿到最新版本，因此每次发布都会在缓存时间内生效。仅在用户明确要求时使用这种方式。

除非用户要求该次发布，否则不要移动正在运行的代码已经拉取的标签。移动 production 会改变应用发送给模型的内容。回滚方式是把标签指回较早版本。

修改已有提示词

调用 posthog:llma-prompt-get 时使用 resolve=false。默认响应会把 @@@prompt:...@@@ 引用替换为被引用内容，若发布该文本，引用会丢失。

调用 posthog:llma-prompt-update 时，base_version 设为读取到的版本，version_description 说明改了什么及原因。返回 409 表示期间有他人发布，应重新读取提示词并把改动应用到新文本上。

告知用户新版本号以及是否有标签指向它。移动标签前先询问。

接入代码

SDK 辅助方法存在于 Python（posthog）和 Node（@posthog/ai 配合 posthog-node）。其他语言应先查阅文档确认当前支持情况，再决定是否手写 HTTP 客户端。

Python 示例：

import os

from posthog import Posthog
from posthog.ai.prompts import Prompts

posthog = Posthog(PROJECT_TOKEN, host="https://us.posthog.com", secret_key=os.environ["POSTHOG_PERSONAL_API_KEY"])
prompts = Prompts(posthog)

result = prompts.get("support-reply-system", label="production", with_metadata=True, fallback=ORIGINAL_PROMPT)
system_prompt = prompts.compile(result.prompt, {"company": company})

Node 示例：

import { Prompts } from '@posthog/ai'
import { PostHog } from 'posthog-node'

const posthog = new PostHog(PROJECT_TOKEN, {
  host: 'https://us.posthog.com',
  personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
})
const prompts = new Prompts({ posthog })

const result = await prompts.get('support-reply-system', { label: 'production', fallback: ORIGINAL_PROMPT })
const systemPrompt = prompts.compile(result.prompt, { company })

容易出错的规则：

  • 拉取需要具有 llm_prompt:read 权限范围的个人 API 密钥，仅有项目 token 不够。你无法创建该密钥，应请用户创建并设置为环境变量或密钥，切勿把密钥写入代码。
  • 使用应用主机 https://us.posthog.com 或 https://eu.posthog.com。诸如 https://us.i.posthog.com 的摄取主机不提供提示词。Prompts 从传入的 PostHog 客户端获取主机；若现有客户端通过摄取主机上报事件，应直接用个人 API 密钥、项目 token 和应用主机构造 Prompts。
  • 在代码中保留原始提示词文本作为 fallback。当无法访问 PostHog 且无缓存时，SDK 会返回它，使应用继续工作。
  • 在模块级别为进程创建一个 Prompts 客户端。每个客户端有自己的缓存，按请求创建客户端会导致每次请求都拉取。
  • 将拉取关联到追踪。若应用向 PostHog 发送 LLM 事件，把 $ai_prompt_name 和 $ai_prompt_version（来自 result.name 和 result.version）作为 PostHog 属性传给模型调用，提示词页面即可显示各版本的追踪。
  • 使用大量提示词的应用可在启动时一次请求全部加载，参见文档中的“Fetching all prompts in one request”。

确认拉取生效

设置了 fallback 时，错误的密钥或主机不会报错。SDK 会记录警告、返回 fallback，应用看起来一切正常。报告成功前必须检查。

  • 若可运行应用或其测试对接真实 API，运行一次代码路径。
  • 读取 result.source：api 或 cache 表示提示词来自 PostHog，code_fallback 表示拉取失败。
  • 从 PostHog 侧用 posthog:execute-sql 确认：
SELECT timestamp, properties.prompt_version, properties.prompt_label
FROM events
WHERE event = '$llm_prompt_fetched'
  AND properties.prompt_name = 'support-reply-system'
  AND timestamp > now() - INTERVAL 1 HOUR
ORDER BY timestamp DESC
LIMIT 10

你自己的 posthog:llma-prompt-get 调用也会产生该事件。只统计应用运行之后时间戳的事件，且不要在运行与查询之间调用 posthog:llma-prompt-get。批量拉取每次请求产生一个事件，带 prompt_count 而无 prompt_name，这种情况应过滤 properties.prompt_fetch_path = 'list'。

若无法运行应用，应说明拉取未经验证，并把该查询交给用户在下次部署后运行。

向用户报告

  • 提示词名称、版本，以及哪个标签指向它。
  • 用户必须设置的环境变量，以及密钥需要 llm_prompt:read 权限范围。
  • 拉取是否已验证，以及如何验证的。
  • 今后如何修改提示词：在 PostHog 中发布新版本，然后移动 production 标签以释放。

适用场景

  • 需要在不重新部署的情况下调整发送给模型的提示词。
  • 希望统一管理提示词的版本、发布与回滚。
  • 需要把散落在代码中的硬编码提示词集中到 PostHog。
  • 需要把提示词版本与 LLM 追踪关联起来分析。

限制

  • 拉取需要具有 llm_prompt:read 权限范围的个人 API 密钥，且该密钥需由用户自行创建。
  • 必须使用应用主机，摄取主机不提供提示词。
  • 提示词名称创建后不可更改，new 为保留名。
  • 设置了 fallback 时，密钥或主机错误不会抛出异常，需主动验证。
  • 其他语言的 SDK 支持情况需查阅文档确认。
  • 资料未提供收费、价格或平台支持范围等信息。