Portkey 集成

简介

Portkey 通过提供以下能力，为 CrewAI 增强生产就绪特性，把你的实验性代理团队转变为稳健系统：

完整可观测性：覆盖每个代理步骤、工具使用和交互
内置可靠性：提供回退、重试和负载均衡
成本跟踪与优化：帮助管理 AI 支出
访问 200+ LLM：通过单一集成即可使用
Guardrails：确保代理行为安全且合规
版本控制提示词：保持代理表现一致

安装与设置

安装所需包
Terminal window
```
pip install -U crewai portkey-ai
```
生成 API Key

在 Portkey dashboard 中创建一个 Portkey API key，并可附加可选的预算/速率限制。你也可以为这个 key 绑定可靠性、缓存等配置。后面会详细说明。

使用 Portkey 配置 CrewAI

集成非常简单 - 你只需要更新 CrewAI 设置中的 LLM 配置：

from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create an LLM instance with Portkey integration
gpt_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",  # We are using a Virtual key, so this is a placeholder
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_LLM_VIRTUAL_KEY",
        trace_id="unique-trace-id",               # Optional, for request tracing
    )
)

#Use them in your Crew Agents like this:

  @agent
  def lead_market_analyst(self) -> Agent:
    return Agent(
      config=self.agents_config['lead_market_analyst'],
      verbose=True,
      memory=False,
      llm=gpt_llm
    )

生产特性

1. 增强的可观测性

Portkey 为你的 CrewAI 代理提供全面可观测性，帮助你准确理解每次执行中发生的事情。

Traces

Traces 提供你 crew 执行的层级视图，展示 LLM 调用、工具调用和状态转换的顺序。

# Add trace_id to enable hierarchical tracing in Portkey
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        trace_id="unique-session-id"  # Add unique trace ID
    )
)

Logs

Portkey 会记录与 LLM 的每次交互，包括：

完整的请求与响应 payload
延迟和 token 使用量指标
成本计算
工具调用和函数执行

所有日志都可以按 metadata、trace ID、模型等条件筛选，因此很容易调试特定的 crew 运行。

Metrics & Dashboards

Portkey 提供内置仪表盘，帮助你：

跟踪所有 crew 运行中的成本和 token 使用量
分析延迟和成功率等性能指标
识别代理工作流中的瓶颈
比较不同 crew 配置和 LLM

你可以按自定义 metadata 筛选和分段所有指标，从而分析特定 crew 类型、用户群或用例。

Metadata Filtering

将自定义 metadata 添加到 CrewAI 的 LLM 配置中，可以启用强大的筛选和分段能力：

portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        metadata={
            "crew_type": "research_crew",
            "environment": "production",
            "_user": "user_123",   # Special _user field for user analytics
            "request_source": "mobile_app"
        }
    )
)

这些 metadata 可用于在 Portkey 仪表盘中筛选日志、追踪和指标，从而分析特定的 crew 运行、用户或环境。

2. 可靠性 - 让你的 crew 稳定运行

在生产环境中运行 crew 时，问题随时可能出现 - API 限流、网络问题或提供商故障。Portkey 的可靠性功能可确保即使出现问题，代理也能持续稳定运行。

在 CrewAI 设置中使用 Portkey Config 启用 fallback 非常简单：

from crewai import LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create LLM with fallback configuration
portkey_llm = LLM(
    model="gpt-4o",
    max_tokens=1000,
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        config={
            "strategy": {
                "mode": "fallback"
            },
            "targets": [
                {
                    "provider": "openai",
                    "api_key": "YOUR_OPENAI_API_KEY",
                    "override_params": {"model": "gpt-4o"}
                },
                {
                    "provider": "anthropic",
                    "api_key": "YOUR_ANTHROPIC_API_KEY",
                    "override_params": {"model": "claude-3-opus-20240229"}
                }
            ]
        }
    )
)

# Use this LLM configuration with your agents

如果 GPT-4o 请求失败，此配置会自动尝试 Claude，确保你的 crew 能继续运行。

Automatic Retries

自动处理临时故障。如果某次 LLM 调用失败，Portkey 会按指定次数重试同一请求，非常适合限流或网络抖动场景。

Request Timeouts

防止代理挂起。设置超时以确保你在需要的时间内收到响应，或者能够优雅失败。

Conditional Routing

将不同请求路由到不同提供商。根据需要把复杂推理路由给 GPT-4，把创意任务路由给 Claude，把快速响应路由给 Gemini。

Fallbacks

即使主提供商失败也能持续运行。自动切换到备用提供商以保持可用性。

Load Balancing

在多个 API key 或提供商之间分摊请求。非常适合高并发 crew 运行，也有助于保持在速率限制内。

3. 在 CrewAI 中进行提示词管理

Portkey 的 Prompt Engineering Studio 帮助你创建、管理并优化 CrewAI 代理所使用的提示词。不要把提示词或指令硬编码，而是使用 Portkey 的提示渲染 API 动态获取并应用版本化提示词。

Prompt Playground

Prompt Playground 是用于比较、测试和部署适合你的 AI 应用的提示词的地方。你可以在这里尝试不同模型、测试变量、比较输出，并在投入生产前完善你的提示工程策略。它允许你：

在将提示词用于代理之前进行迭代式开发
使用不同变量和模型测试提示词
比较不同提示版本之间的输出
与团队成员协作进行提示开发

这个可视化环境让你更容易为 CrewAI 代理工作流中的每一步打造有效提示词。

Using Prompt Templates

Prompt Render API 会检索已配置好所有参数的提示模板：

from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL, Portkey

# Initialize Portkey admin client
portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY")

# Retrieve prompt using the render API
prompt_data = portkey_client.prompts.render(
    prompt_id="YOUR_PROMPT_ID",
    variables={
        "agent_role": "Senior Research Scientist",
        "agent_goal": "Discover groundbreaking insights",
    }
)

backstory_agent_prompt=prompt_data.data.messages[0]["content"]


# Set up LLM with Portkey integration
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY"
    )
)

# Create agent using the rendered prompt
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory=backstory_agent,  # Use the rendered prompt
    verbose=True,
    llm=portkey_llm
)

Prompt Versioning

你可以：

创建同一提示词的多个版本
比较不同版本的表现
在需要时回滚到先前版本
在代码中指定要使用的版本：

# Use a specific prompt version
prompt_data = portkey_admin.prompts.render(
    prompt_id="YOUR_PROMPT_ID@version_number",
    variables={
        "agent_role": "Senior Research Scientist",
        "agent_goal": "Discover groundbreaking insights"
    }
)

Mustache Templating for variables

Portkey prompts 使用 Mustache 风格模板，便于进行变量替换：

You are a {{agent_role}} with expertise in {{domain}}.

Your mission is to {{agent_goal}} by leveraging your knowledge
and experience in the field.

Always maintain a {{tone}} tone and focus on providing {{focus_area}}.

渲染时，只需传入变量：

prompt_data = portkey_admin.prompts.render(
    prompt_id="YOUR_PROMPT_ID",
    variables={
        "agent_role": "Senior Research Scientist",
        "domain": "artificial intelligence",
        "agent_goal": "discover groundbreaking insights",
        "tone": "professional",
        "focus_area": "practical applications"
    }
)

Prompt Engineering Studio

了解更多 Portkey 的提示管理功能

4. 为安全 crew 添加 Guardrails

Guardrails 可确保你的 CrewAI 代理在所有情况下都安全运行并给出合适响应。

为什么使用 Guardrails？

CrewAI 代理可能会遇到多种失败模式：

生成有害或不当内容
泄露 PII 等敏感信息
幻觉出错误信息
生成格式不正确的输出

Portkey 的 guardrails 会为输入和输出都增加保护。

实现 Guardrails

from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Create LLM with guardrails
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "input_guardrails": ["guardrails-id-xxx", "guardrails-id-yyy"],
            "output_guardrails": ["guardrails-id-zzz"]
        }
    )
)

# Create agent with guardrailed LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

Portkey 的 guardrails 可以：

在输入和输出中检测并脱敏 PII
过滤有害或不当内容
根据 schema 验证响应格式
对照真实答案检查幻觉
应用自定义业务逻辑和规则

了解更多 Guardrails

探索 Portkey 的 guardrail 功能，增强代理安全性

5. 使用 Metadata 进行用户跟踪

借助 Portkey 的 metadata 系统，通过你的 CrewAI 代理跟踪单个用户。

什么是 Portkey 中的 Metadata？

Metadata 允许你将自定义数据附加到每个请求，便于筛选、分段和分析。特殊的 _user 字段专门用于用户跟踪。

from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLM with user tracking
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        metadata={
            "_user": "user_123",  # Special _user field for user analytics
            "user_tier": "premium",
            "user_company": "Acme Corp",
            "session_id": "abc-123"
        }
    )
)

# Create agent with tracked LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

按用户筛选分析

配置好 metadata 后，你就可以按用户筛选分析，并在用户维度上查看性能指标：

这可以实现：

按用户进行成本跟踪和预算控制
个性化用户分析
团队或组织级指标
按环境进行监控（staging vs. production）

了解更多 Metadata

探索如何使用自定义 metadata 来增强分析

6. 用缓存提升 crew 效率

通过缓存，让你的 CrewAI 代理更高效、更节省成本：

Simple Caching

from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLM with simple caching
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "cache": {
                "mode": "simple"
            }
        }
    )
)

# Create agent with cached LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

简单缓存会对输入提示做完全匹配，将相同请求缓存起来，从而避免重复执行模型。

Semantic Caching

from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Configure LLM with semantic caching
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY",
        config={
            "cache": {
                "mode": "semantic"
            }
        }
    )
)

# Create agent with semantically cached LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

语义缓存会考虑输入请求之间的上下文相似度，为语义相近的输入缓存响应。

7. 模型互操作性

CrewAI 支持多个 LLM 提供商，而 Portkey 通过统一接口提供对 200+ LLM 的访问能力。你可以在不改动核心代理逻辑的情况下轻松切换不同模型：

from crewai import Agent, LLM
from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL

# Set up LLMs with different providers
openai_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_OPENAI_VIRTUAL_KEY"
    )
)

anthropic_llm = LLM(
    model="claude-3-5-sonnet-latest",
    max_tokens=1000,
    base_url=PORTKEY_GATEWAY_URL,
    api_key="dummy",
    extra_headers=createHeaders(
        api_key="YOUR_PORTKEY_API_KEY",
        virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY"
    )
)

# Choose which LLM to use for each agent based on your needs
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=openai_llm  # Use anthropic_llm for Anthropic
)

Portkey 提供对以下提供商的 LLM 访问：

OpenAI（GPT-4o、GPT-4 Turbo 等）
Anthropic（Claude 3.5 Sonnet、Claude 3 Opus 等）
Mistral AI（Mistral Large、Mistral Medium 等）
Google Vertex AI（Gemini 1.5 Pro 等）
Cohere（Command、Command-R 等）
AWS Bedrock（Claude、Titan 等）
本地/私有模型

Supported Providers

查看 Portkey 支持的完整 LLM 提供商列表

为 CrewAI 建立企业治理

为什么需要企业治理？ 如果你在组织内部使用 CrewAI，需要考虑以下治理方面：

成本管理：控制和跟踪跨团队 AI 支出
访问控制：管理哪些团队可以使用哪些模型
使用分析：了解 AI 在整个组织中的使用方式
安全与合规：维持企业级安全标准
可靠性：确保所有用户都能获得一致的服务

Portkey 为这些企业需求添加了一个全面的治理层。下面我们逐步实现这些控制。

创建 Virtual Key

Virtual Keys 是 Portkey 管理 LLM 提供商 API key 的安全方式。它们提供以下关键控制：
- API 使用预算限制
- 速率限制能力
- 安全的 API key 存储
要创建 virtual key：进入 Portkey App 的 Virtual Keys。保存并复制 virtual key ID。

Note

保存你的 virtual key ID - 下一步会用到它。
创建默认 Config

Portkey 中的 Config 定义了请求如何被路由，并提供高级路由、回退和重试等能力。
创建 config 的方法：
1. 打开 Portkey dashboard 的 Configs
2. 创建新的 config，内容如下：
```
{
    "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1",
     "override_params": {
      "model": "gpt-4o" // Your preferred model name
    }
}
```
3. 保存并记下 Config 名称，供下一步使用
配置 Portkey API Key

现在创建一个 Portkey API key，并将你在第 2 步创建的 config 关联上：
1. 进入 Portkey 的 API Keys 页面并创建新的 API key
2. 从 Step 2 中选择你的 config
3. 生成并保存 API key

连接到 CrewAI

在为团队成员分发带有关联 config 的 Portkey API key 之后，就可以把它连接到你的 CrewAI 代理：

from crewai import Agent, LLM
from portkey_ai import PORTKEY_GATEWAY_URL

# Configure LLM with your API key
portkey_llm = LLM(
    model="gpt-4o",
    base_url=PORTKEY_GATEWAY_URL,
    api_key="YOUR_PORTKEY_API_KEY"
)

# Create agent with Portkey-enabled LLM
researcher = Agent(
    role="Senior Research Scientist",
    goal="Discover groundbreaking insights about the assigned topic",
    backstory="You are an expert researcher with deep domain knowledge.",
    verbose=True,
    llm=portkey_llm
)

第 1 步：实现预算控制与速率限制

Virtual Keys 让你可以在团队/部门级别对 LLM 访问进行精细控制。这有助于你：

设置预算上限
使用速率限制防止意外的使用峰值
跟踪部门支出

设置部门级控制：

在 Portkey dashboard 中进入 Virtual Keys
为每个部门创建带有预算限制和速率限制的新 Virtual Key
配置部门专属限制

第 2 步：定义模型访问规则

随着 AI 使用规模扩大，控制哪些团队可以访问哪些模型变得至关重要。Portkey Config 提供了这一控制层，具备以下特性：

访问控制特性：

模型限制：限制对特定模型的访问
数据保护：为敏感数据实施 guardrails
可靠性控制：添加回退和重试逻辑

示例配置：

下面是一个将请求路由到 OpenAI、并使用 GPT-4o 的基础配置：

{
  "strategy": {
    "mode": "single"
  },
  "targets": [
    {
      "virtual_key": "YOUR_OPENAI_VIRTUAL_KEY",
      "override_params": {
        "model": "gpt-4o"
      }
    }
  ]
}

在 Portkey dashboard 的 Configs page 上创建你的 config。

第 3 步：实现访问控制

创建面向用户的 API key，它会自动：

在 virtual key 的帮助下按用户/团队跟踪使用情况
应用合适的 config 来路由请求
收集相关 metadata 以便筛选日志
执行访问权限控制

通过 Portkey App 创建 API key

使用 Python SDK 的示例：

from portkey_ai import Portkey

portkey = Portkey(api_key="YOUR_ADMIN_API_KEY")

api_key = portkey.api_keys.create(
    name="engineering-team",
    type="organisation",
    workspace_id="YOUR_WORKSPACE_ID",
    defaults={
        "config_id": "your-config-id",
        "metadata": {
            "environment": "production",
            "department": "engineering"
        }
    },
    scopes=["logs.view", "configs.read"]
)

有关密钥管理的详细说明，请参阅 Portkey 文档。

第 4 步：部署与监控

将 API key 分发给团队成员后，你的企业级 CrewAI 配置就可以投入使用了。每位团队成员现在都可以使用各自分配的 API key，并获得合适的访问级别和预算控制。

在 Portkey dashboard 中监控使用情况：

按部门跟踪成本
模型使用模式
请求量
错误率

常见问题

Portkey 如何增强 CrewAI？

Portkey 通过全面的可观测性（traces、logs、metrics）、可靠性功能（回退、重试、缓存），以及通过统一接口访问 200+ LLM，为 CrewAI 增加生产就绪能力。这使得调试、优化和扩展代理应用更容易。

我可以在现有 CrewAI 应用中使用 Portkey 吗？

可以！Portkey 可以与现有 CrewAI 应用无缝集成。你只需要把 LLM 配置代码更新为 Portkey 版本，其余代理和 crew 代码保持不变。

Portkey 是否支持所有 CrewAI 功能？

Portkey 支持所有 CrewAI 功能，包括代理、工具、human-in-the-loop 工作流，以及所有任务流程类型（sequential、hierarchical 等）。它在不限制框架功能的前提下，增加了可观测性和可靠性。

我可以跟踪 crew 中多个代理的使用情况吗？

可以，Portkey 允许你在 crew 中的多个代理之间使用一致的 trace_id，以跟踪整个工作流。这对于希望理解多代理完整执行路径的复杂 crew 尤其有用。

如何筛选特定 crew 运行的日志和追踪？

Portkey 允许你为 LLM 配置添加自定义 metadata，然后用于筛选。添加 crew_name、crew_type 或 session_id 等字段，就可以轻松找到并分析特定的 crew 执行。

我可以在 Portkey 中使用自己的 API key 吗？

可以！Portkey 会使用你自己的 LLM 提供商 API key。它会将它们安全存储为 virtual keys，让你无需改动代码即可轻松管理和轮换密钥。