Portkey 集成 - CrewAI 框架

简介

Portkey 通过提供生产就绪功能来增强 CrewAI，将您的实验性智能体团队转变为强大的系统，具体包括：

完全的可观测性，覆盖每个智能体步骤、工具使用和交互
内置的可靠性，具备故障回退、重试和负载均衡功能
成本跟踪与优化，帮助您管理 AI 支出
通过单一集成访问 200 多个 LLM
安全护栏，确保智能体行为安全合规
版本控制的提示词，保证智能体性能的一致性

安装与设置

安装所需软件包

pip install -U crewai portkey-ai

生成 API 密钥

从 Portkey 仪表板创建一个 Portkey API 密钥，并可选择性地设置预算/速率限制。您还可以为此密钥附加可靠性、缓存等配置。稍后将详细介绍。

使用 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
		)

什么是虚拟密钥？ Portkey 中的虚拟密钥将您的 LLM 提供商 API 密钥（如 OpenAI、Anthropic 等）安全地存储在加密保险库中。它们可以更轻松地进行密钥轮换和预算管理。在此处了解更多关于虚拟密钥的信息。

生产功能

1. 增强的可观测性

Portkey 为您的 CrewAI 智能体提供了全面的可观测性，帮助您准确了解每次执行期间发生的情况。

追踪
日志
指标与仪表板
元数据过滤

追踪提供了您团队执行的分层视图，显示了 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
    )
)

2. 可靠性 - 确保您的团队平稳运行

在生产环境中运行团队时，可能会出现问题——API 速率限制、网络问题或提供商中断。Portkey 的可靠性功能可确保即使出现问题，您的智能体也能继续平稳运行。通过使用 Portkey 配置，在您的 CrewAI 设置中启用故障回退非常简单：

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，确保您的团队能够继续运作。

自动重试

自动处理临时故障。如果 LLM 调用失败，Portkey 将按指定次数重试相同的请求——非常适合处理速率限制或网络抖动。

请求超时

防止您的智能体卡住。设置超时以确保您在所需时间内获得响应（或能够优雅地处理失败）。

条件路由

将不同的请求发送给不同的提供商。根据您的需求，将复杂的推理任务路由到 GPT-4，创造性任务路由到 Claude，快速响应则路由到 Gemini。

故障回退

即使您的主要提供商失败，也能继续运行。自动切换到备用提供商以维持可用性。

负载均衡

将请求分散到多个 API 密钥或提供商。非常适合高流量的团队操作并保持在速率限制内。

3. 在 CrewAI 中使用提示词

Portkey 的提示工程工作室帮助您创建、管理和优化在 CrewAI 智能体中使用的提示词。您可以使用 Portkey 的提示词渲染 API 动态获取并应用版本化的提示词，而不是硬编码提示词或指令。

在 Portkey 的提示词库中管理提示词

提示词游乐场
使用提示词模板
提示词版本控制
使用 Mustache 模板处理变量

提示词游乐场是一个用于比较、测试和部署完美提示词到您的 AI 应用的地方。在这里，您可以试验不同的模型、测试变量、比较输出，并在部署到生产环境之前完善您的提示工程策略。它允许您

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

这个可视化环境使为 CrewAI 智能体工作流程中的每一步制作有效的提示词变得更加容易。

提示工程工作室

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

4. 为安全的团队设置安全护栏

安全护栏确保您的 CrewAI 智能体在所有情况下都能安全操作并做出适当的响应。 为什么要使用安全护栏？ CrewAI 智能体可能会遇到各种故障模式：

生成有害或不当内容
泄露个人可识别信息（PII）等敏感信息
产生不正确信息的幻觉
生成格式不正确的输出

Portkey 的安全护栏为输入和输出都增加了保护。 实施安全护栏

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 的安全护栏可以

检测并编辑输入和输出中的个人可识别信息（PII）
过滤有害或不当内容
根据模式验证响应格式
对照事实基础检查幻觉
应用自定义业务逻辑和规则

了解更多关于安全护栏的信息

探索 Portkey 的安全护栏功能以增强智能体安全性

5. 使用元数据进行用户跟踪

使用 Portkey 的元数据系统，在您的 CrewAI 智能体中跟踪单个用户。 Portkey 中的元数据是什么？ 元数据允许您将自定义数据与每个请求关联起来，从而实现过滤、分段和分析。特殊的 _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
)

按用户筛选分析 有了元数据，您可以按用户筛选分析结果，并按用户分析性能指标：

按用户筛选分析

这可以实现

按用户进行成本跟踪和预算编制
个性化用户分析
团队或组织级别的指标
特定环境的监控（预发布环境 vs. 生产环境）

了解更多关于元数据的信息

探索如何使用自定义元数据来增强您的分析

6. 为高效团队设置缓存

实施缓存，使您的 CrewAI 智能体更高效、更具成本效益

简单缓存
语义缓存

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
)

简单缓存对输入提示进行精确匹配，缓存相同的请求以避免冗余的模型执行。

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 等）
本地/私有模型

支持的提供商

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

为 CrewAI 设置企业级治理

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

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

Portkey 增加了一个全面的治理层来满足这些企业需求。让我们一步步实现这些控制。

创建虚拟密钥

虚拟密钥是 Portkey 管理您的 LLM 提供商 API 密钥的安全方式。它们提供了必要的控制，如

API 使用的预算限制
速率限制功能
安全的 API 密钥存储

要创建虚拟密钥：在 Portkey 应用中前往虚拟密钥。保存并复制虚拟密钥 ID

保存您的虚拟密钥 ID——下一步会用到它。

创建默认配置

Portkey 中的配置定义了您的请求如何被路由，并具备高级路由、故障回退和重试等功能。要创建您的配置：

在 Portkey 仪表板中前往配置

创建新配置

{
    "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1",
   	"override_params": {
      "model": "gpt-4o" // Your preferred model name
    }
}

保存并记下配置名称，以备下一步使用

配置 Portkey API 密钥

现在创建一个 Portkey API 密钥，并附加您在第 2 步中创建的配置

在 Portkey 中前往API 密钥并创建新的 API 密钥
从第 2 步中选择您的配置
生成并保存您的 API 密钥

连接到 CrewAI

在设置好附带配置的 Portkey API 密钥后，将其连接到您的 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 步：实施预算控制和速率限制

虚拟密钥可以在团队/部门级别对 LLM 访问进行精细控制。这可以帮助您

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

设置部门特定的控制

在 Portkey 仪表板中导航至虚拟密钥
为每个部门创建新的虚拟密钥，并设置预算和速率限制
配置部门特定的限制

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

随着您的 AI 使用规模扩大，控制哪些团队可以访问特定模型变得至关重要。Portkey 配置提供了这个控制层，具有以下功能：

访问控制功能

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

配置示例

这是一个将请求路由到 OpenAI，并特别使用 GPT-4o 的基本配置

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

在您的 Portkey 仪表板的配置页面上创建您的配置。

配置可以随时更新以调整控制，而不会影响正在运行的应用程序。

第 3 步：实施访问控制

创建用户特定的 API 密钥，这些密钥会自动

借助虚拟密钥跟踪每个用户/团队的使用情况
应用适当的配置来路由请求
收集相关元数据以过滤日志
强制执行访问权限

通过以下方式创建 API 密钥

使用 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"]
)

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

第 4 步：部署与监控

向您的团队成员分发 API 密钥后，您的企业级 CrewAI 设置就准备就绪了。现在，每个团队成员都可以使用他们指定的 API 密钥，并享有适当的访问级别和预算控制。在 Portkey 仪表板中监控使用情况：

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

企业功能现已可用

您的 CrewAI 集成现在具备了

部门预算控制
模型访问治理
使用情况跟踪与归因
安全护栏
可靠性功能

常见问题解答

Portkey 如何增强 CrewAI？

Portkey 通过全面的可观测性（追踪、日志、指标）、可靠性功能（故障回退、重试、缓存）以及通过统一接口访问 200 多个 LLM，为 CrewAI 增加了生产就绪性。这使得调试、优化和扩展您的智能体应用程序变得更加容易。

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

是的！Portkey 与现有的 CrewAI 应用程序无缝集成。您只需将您的 LLM 配置代码更新为启用 Portkey 的版本即可。您的其他智能体和团队代码保持不变。

Portkey 是否支持所有 CrewAI 功能？

Portkey 支持所有 CrewAI 功能，包括智能体、工具、人在环路工作流以及所有任务处理类型（顺序、分层等）。它在不限制框架任何功能的情况下，增加了可观测性和可靠性。

我可以在一个团队中跟踪多个智能体的使用情况吗？

是的，Portkey 允许您在一个团队中的多个智能体之间使用一致的 trace_id 来跟踪整个工作流。这对于复杂的团队特别有用，因为您希望了解跨多个智能体的完整执行路径。

如何为特定的团队运行筛选日志和追踪？

Portkey 允许您向 LLM 配置中添加自定义元数据，然后您可以使用这些元数据进行筛选。添加诸如 crew_name、crew_type 或 session_id 之类的字段，以便轻松查找和分析特定的团队执行情况。

我可以使用自己的 API 密钥与 Portkey 吗？

是的！Portkey 使用您自己的 API 密钥来连接各种 LLM 提供商。它将它们安全地存储为虚拟密钥，使您可以轻松管理和轮换密钥，而无需更改代码。

开始使用

指南

核心概念

MCP 集成

工具

可观测性

学习

遥测

​简介

​安装与设置

​生产功能

​1. 增强的可观测性

​2. 可靠性 - 确保您的团队平稳运行

自动重试

请求超时

条件路由

故障回退

负载均衡

​3. 在 CrewAI 中使用提示词

提示工程工作室

​4. 为安全的团队设置安全护栏

了解更多关于安全护栏的信息

​5. 使用元数据进行用户跟踪

了解更多关于元数据的信息

​6. 为高效团队设置缓存

​7. 模型互操作性

支持的提供商

​为 CrewAI 设置企业级治理

​第 1 步：实施预算控制和速率限制

​设置部门特定的控制

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

​访问控制功能

​配置示例

​第 3 步：实施访问控制

​第 4 步：部署与监控

​企业功能现已可用

​常见问题解答

​资源

CrewAI 文档

预约演示

简介

安装与设置

生产功能

1. 增强的可观测性

2. 可靠性 - 确保您的团队平稳运行

3. 在 CrewAI 中使用提示词

4. 为安全的团队设置安全护栏

5. 使用元数据进行用户跟踪

6. 为高效团队设置缓存

7. 模型互操作性

为 CrewAI 设置企业级治理

第 1 步：实施预算控制和速率限制

设置部门特定的控制

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

访问控制功能

配置示例

第 3 步：实施访问控制

第 4 步：部署与监控

企业功能现已可用

常见问题解答

资源