> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 提示词管理

提示词管理让团队可以在 Alephant SaaS 仪表板中创建可复用的提示词模板，为每个模板分配稳定 ID，并通过 Alephant AI Gateway 在运行时调用它。

无需在应用代码中硬编码提示词；只需在 Alephant 中创建一次提示词，将经测试的版本提升至生产环境，并在每次请求中发送提示词 ID。

```typescript
Alephant-Prompt-ID: support-triage
```

Alephant 会应用生产提示词模板，将请求转发至选定模型，并记录 Token 用量、成本、延迟、路由、智能体、用户和会话元数据。

## **核心流程**

1. 在 Alephant 仪表板中创建提示词模板。

2. 设置稳定的提示词 ID，例如 support-triage。

3. 添加 system、user 或 assistant 消息片段。

4. 配置模型绑定和参数。

5. 将经测试的版本提升至生产环境。

6. 使用 Alephant-Prompt-ID 调用网关。

## **创建模板**

在 **提示词管理** 中，创建一个新模板并配置：

| **字段** | **说明**                              |
| ------ | ----------------------------------- |
| ID     | 在 Alephant-Prompt-ID 请求头中使用的运行时 ID。 |
| 模板名称   | 仪表板中的显示名称。                          |
| LLM 绑定 | 提示词的提供商/模型配置。                       |
| 参数     | Temperature、max tokens 和 top P。     |
| 消息     | 可复用的提示词消息。                          |
| 变量     | 动态占位符，例如 \{\{customer\_name}}。      |
| 状态     | Draft、Production 或 Archived。        |

请使用应用可依赖的稳定 ID：

support-triage\
security-code-audit\
hermes-planner\
openclaw-browser-agent\
\
**在运行时调用提示词**

通过 Alephant 发送普通模型请求，并包含提示词 ID 请求头。

```typescript
curl https://ai.alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Alephant-Prompt-ID: support-triage" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Customer says their AI invoice increased last night. Explain what happened."
      }
    ]
  }'
```

Alephant 会将生产模板消息前置于你发送的运行时消息。

## **使用变量**

*提示词模板可以包含变量：*

`You are helping {customer_name} on the {plan_name} plan
Limit the response to {max_items} action items`

*在 inputs 中传递变量值：*

```typescript
{
  "model": "openai/gpt-4o-mini",
  "inputs": {
    "customer_name": "Acme",
    "plan_name": "Team",
    "max_items": 3
  },
  "messages": [
    {
      "role": "user",
      "content": "Summarize the usage spike."
    }
  ]
}
```

如果缺少必填变量，Alephant 会在分发至提供商前拒绝请求。

## **版本管理**

每次保存都会创建一个新的提示词版本。

| **状态**     | **用途**                       |
| ---------- | ---------------------------- |
| Draft      | 安全地编辑和测试。                    |
| Production | Alephant-Prompt-ID 使用的运行时版本。 |
| Archived   | 为历史记录保留的已弃用版本。               |

当希望同一提示词 ID 后续的运行时调用使用某个版本时，将该版本提升至生产环境。

## **提示词成本台账**

提示词管理也是提示词资产的成本台账。每个由提示词管理的请求都可以归因到：

* 提示词 ID
* 提示词版本
* 绑定的模型和提供商
* 智能体或 Virtual Key
* 会话或运行上下文
* 输入 Token、输出 Token、成本、延迟和状态

这让团队能按成本和运维影响比较提示词版本，而不仅是比较文本差异。

## **模型绑定与路由**

模板可以绑定默认模型和参数。策略允许时，团队无需修改应用代码，即可将模板路由至成本更低的模型。

请在以下情况使用此模式：

* 提示词稳定且经常复用
* 同一提示词支持多个智能体或工作流
* 提示词版本在提升前需要进行成本比较
* 团队希望将简单工作迁移至成本较低的模型

模型绑定仍遵循工作区、智能体、部门和 Virtual Key 策略。提示词路由不应覆盖模型允许列表、预算硬性停止或安全策略。

## **缓存机会**

由于稳定的提示词前缀会在请求之间重复，提示词模板可以改善缓存行为。

Alephant 可以追踪：

* 提供商支持时的原生提示词缓存效果
* 重复模板和变量组合的网关精确匹配缓存机会
* 请求日志上的缓存命中或未命中元数据
* 重复使用提示词节省的成本

请谨慎使用提示词变量。变化极大的提示词正文会降低精确匹配复用率，而稳定的系统提示词和结构化变量能让成本更易比较。

## **成本与可观测性**

由提示词管理的请求会按提示词 ID 和版本归因。

仪表板可以展示：

* 调用次数
* Token 用量
* 提示词成本
* 模型和提供商
* 路由
* 延迟
* 关联的智能体、Virtual Key、用户和会话
* 错误或被阻止的请求

这有助于团队了解哪些提示词正在驱动支出，以及新提示词版本是否增加了 Token 用量或成本。

## **说明**

| **情形**                | **行为**             |
| --------------------- | ------------------ |
| 没有 Alephant-Prompt-ID | 请求正常运行，不注入提示词。     |
| 有效的生产提示词 ID           | Alephant 应用生产模板。   |
| 缺少变量的 inputs          | 请求在分发至提供商前被拒绝。     |
| 仅 Draft 状态的提示词        | 依赖运行时调用前，请先提升一个版本。 |

请求头名称不区分大小写。推荐形式为：

```typescript
curl https://ai.alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "Alephant-Prompt-ID: support-triage" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "The customer asks why AI usage increased last night."
      }
    ]
  }'
```