instrument-llm-analytics

添加 PostHog AI 可观测性

使用此技能添加 PostHog AI 可观测性，以跟踪新增或修改代码中的 AI 模型用量。在实现 LLM 功能或审查 PR 后使用此技能，确保记录所有生成操作的令牌数、延迟和成本。如果尚未安装 PostHog，此技能也涵盖 SDK 的初始设置。支持任何提供方或框架。

支持的提供方：OpenAI、Azure OpenAI、Anthropic、Google、Cohere、Mistral、Perplexity、DeepSeek、Groq、Together AI、Fireworks AI、xAI、Cerebras、Hugging Face、Ollama、OpenRouter。

支持的框架：LangChain、LlamaIndex、CrewAI、AutoGen、DSPy、LangGraph、Pydantic AI、Vercel AI、LiteLLM、Instructor、Semantic Kernel、Mirascope、Mastra、SmolAgents、OpenAI Agents。

代理／网关：Portkey、Helicone。

说明

按顺序执行以下步骤：

步骤 1：分析代码库并检测 LLM 技术栈。

• 在依赖文件和导入语句中查找 LLM 提供方 SDK（openai、anthropic、google-generativeai 等）和 AI 框架（langchain、llamaindex、crewai 等）。
• 查找锁文件以确定包管理器。
• 检查现有的 PostHog 或可观测性设置。如果已安装 PostHog 并配置了 LLM 跟踪，则跳到步骤 4，为任何新的 LLM 调用添加跟踪。

步骤 2：调研插桩方式。（如果已设置 PostHog LLM 跟踪，则跳过。） 2.1. 找到下方与检测到的提供方或框架匹配的参考文件——该文件是回调设置、中间件配置和事件采集的权威来源。现在阅读该文件。 2.2. 如果没有匹配的参考文件，则使用 manual-capture.md 作为后备方案——其中涵盖了适用于任何提供方的通用事件采集方法。

步骤 3：安装 PostHog SDK。（如果已设置 PostHog，则跳过。）

• 添加 PostHog SDK 以及任何必需的回调／集成包。
• 不要手动编辑依赖文件——使用包管理器的安装命令。

步骤 4：添加 LLM 跟踪。

• 为 LLM 调用添加插桩，以便记录每次生成的输入令牌数、输出令牌数、模型名称、延迟和成本。
• 按照提供方专用参考文件中的具体回调／中间件设置进行操作。
• 不要改变现有文件的基本架构。仅进行最少且针对性明确的修改。
• 尝试写入文件前，必须立即读取该文件。

步骤 5：关联用户。

• 尽可能通过 distinct ID 将 LLM 生成操作关联到已识别的用户。

步骤 6：设置环境变量。

• 检查项目是否已配置 PostHog 环境变量（例如，在 .env、.env.local 或框架专用环境文件中）。如果已有有效值，则跳过此步骤。
• 如果缺少 PostHog 项目令牌，则使用 PostHog MCP 服务的 projects-get 工具获取项目的 api_token。如果返回多个项目，请询问用户要使用哪个项目。如果 MCP 服务未连接或未经身份验证，则请用户提供 PostHog 项目令牌。
• 对于 PostHog 主机 URL：检查 projects-get MCP 响应中的 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com。如果 MCP 响应或现有项目配置中没有提供区域信息，请询问用户：“您使用的是 PostHog US Cloud 还是 EU Cloud？”不要默认使用 US Cloud。
• 按照框架的命名约定将这些值写入相应的环境文件。
• 在代码中引用这些环境变量，而不是将值硬编码。

参考文件

• references/openai.md - Openai 可观测性安装
• references/azure-openai.md - Azure openai 可观测性安装
• references/README.md - 适用于 .net 的 PostHog.ai
• references/anthropic.md - Anthropic ai 可观测性安装
• references/google.md - Google ai 可观测性安装
• references/cohere.md - Cohere ai 可观测性安装
• references/mistral.md - Mistral ai 可观测性安装
• references/perplexity.md - Perplexity ai 可观测性安装
• references/deepseek.md - Deepseek ai 可观测性安装
• references/groq.md - Groq ai 可观测性安装
• references/together-ai.md - Together ai 可观测性安装
• references/fireworks-ai.md - Fireworks ai 可观测性安装
• references/xai.md - Xai 可观测性安装
• references/cerebras.md - Cerebras ai 可观测性安装
• references/hugging-face.md - Hugging face ai 可观测性安装
• references/ollama.md - Ollama ai 可观测性安装
• references/openrouter.md - Openrouter ai 可观测性安装
• references/langchain.md - Langchain ai 可观测性安装
• references/llamaindex.md - Llamaindex ai 可观测性安装
• references/crewai.md - Crewai 可观测性安装
• references/autogen.md - Autogen ai 可观测性安装
• references/dspy.md - Dspy ai 可观测性安装
• references/langgraph.md - Langgraph ai 可观测性安装
• references/pydantic-ai.md - Pydantic ai 可观测性安装
• references/vercel-ai.md - Vercel ai SDK 可观测性安装
• references/litellm.md - Litellm ai 可观测性安装
• references/instructor.md - Instructor ai 可观测性安装
• references/semantic-kernel.md - Semantic kernel ai 可观测性安装
• references/mirascope.md - Mirascope ai 可观测性安装
• references/mastra.md - Mastra ai 可观测性安装
• references/smolagents.md - Smolagents ai 可观测性安装
• references/openai-agents.md - Openai agents SDK 可观测性安装
• references/portkey.md - Portkey ai 可观测性安装
• references/helicone.md - Helicone ai 可观测性安装
• references/manual-capture.md - 手动捕获 ai 可观测性安装
• references/basics.md - ai 可观测性基础
• references/traces.md - 追踪
• references/calculating-costs.md - 计算 llm 成本
• references/COMMANDMENTS.md - 集成必须遵循的框架特定规则

每份提供方参考文件都包含安装说明、SDK 设置，以及针对该提供方或框架的代码示例。请查找与用户技术栈匹配的参考文件。

如果用户使用的提供方未列出，请使用 manual-capture.md 作为备用方案——其中介绍了适用于任何提供方的通用事件捕获方法。

核心原则

• 环境变量：PostHog 和 LLM 提供方密钥始终使用环境变量。切勿将其硬编码。
• 最小改动：在现有 LLM 调用旁添加 LLM 分析。不要替换或重构现有代码。
• 追踪所有生成：捕获每次 LLM 调用的输入令牌、输出令牌、模型名称、延迟和成本。
• 关联用户：尽可能通过 distinct ID 将 LLM 生成与已识别用户关联。
• 一次集成一个提供方：仅对用户实际使用的提供方进行插桩。不要为代码库中不存在的提供方添加插桩。