> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Python SDK 运行

> 使用 fetch-hive-sdk 包从 Python 调用提示词部署

# 使用 Python SDK 运行

当你想从 Python 调用提示词部署时，请使用官方的 `fetch-hive-sdk` 包。SDK 使用符合 Python 风格的辅助函数包装了公共的 [`POST /v1/prompt/invoke`](../api-reference/prompts/invoke) 端点，处理身份验证，并为你解析流式响应。

## 安装

```bash theme={null}
pip install fetch-hive-sdk
```

SDK 需要 Python 3.9+，底层使用 `httpx`。

## 身份验证

将 `FETCH_HIVE_API_KEY` 环境变量设置为你的工作区 API 密钥（SDK 会自动读取它）：

```bash theme={null}
export FETCH_HIVE_API_KEY=fhk_...
```

```python theme={null}
from fetch_hive_sdk import FetchHive

client = FetchHive()
```

或显式传入密钥：

```python theme={null}
client = FetchHive(api_key="fhk_...")
```

有关如何创建和轮换密钥，请参阅 [API 密钥](../workspace/api-keys)。

## 基本示例

调用提示词部署并读取最终响应：

```python theme={null}
from fetch_hive_sdk import FetchHive

client = FetchHive()

result = client.invoke_prompt(
    deployment="YOUR_DEPLOYMENT_NAME",
    variant="YOUR_VARIANT_NAME",
    inputs={"text": "Fetch Hive helps teams ship AI products faster."},
)

print(result["response"])
```

`invoke_prompt` 是同步的，并在提示词完成后返回已解析的 JSON 主体。请参阅 [非流式响应结构](../api-reference/prompts/invoke#response)。

## 方法参考

| 参数           | 类型                                               | 必填 | 描述                                                                  |
| ------------ | ------------------------------------------------ | -- | ------------------------------------------------------------------- |
| `deployment` | `str`                                            | 是  | 提示词部署名称                                                             |
| `variant`    | `str`                                            | 否  | 部署变体名称                                                              |
| `inputs`     | `dict[str, Any]`                                 | 否  | 提示词变量的键值对                                                           |
| `user`       | `str`                                            | 否  | 在 [用户跟踪](../user-tracking/overview) 中显示的不透明调用方标识符                   |
| `metadata`   | `dict[str, str \| int \| float \| bool \| None]` | 否  | 调用方定义的扁平元数据，用于审计和日志过滤。请参阅 [调用元数据](../user-tracking/invoke-metadata) |

SDK 会为 `invoke_prompt` 注入 `streaming: false`。要使用流式，请使用下面的 `invoke_prompt_stream`。

## 处理响应

非流式响应是一个普通的 `dict`：

```python theme={null}
result = client.invoke_prompt(deployment="my-prompt", variant="default")

print(result["response"])       # final text
print(result["model"])          # model identifier
print(result["usage"])          # token usage breakdown
print(result["request_id"])     # use this to look up the run in Logs
```

## 流式响应

使用 `invoke_prompt_stream` 在到达时接收 Server-Sent Events。该方法返回一个生成器，逐个产出已解析的事件字典：

```python theme={null}
for chunk in client.invoke_prompt_stream(
    deployment="YOUR_DEPLOYMENT_NAME",
    variant="YOUR_VARIANT_NAME",
    inputs={"text": "Fetch Hive helps teams ship AI products faster."},
):
    if chunk.get("type") == "response":
        print(chunk.get("response", ""), end="", flush=True)
    elif chunk.get("type") == "usage":
        print("\n\nUsage:", chunk["usage"])
```

该流会产生 [调用提示词 → 响应](../api-reference/prompts/invoke#response) 中记录的相同事件类型：`reasoning`、`response`、最终的 `usage` 事件，或在提供商在流中失败时产生的 `error` 事件。

### 异步流式

对于 `asyncio` 应用，请使用 `ainvoke_prompt_stream`。它具有相同的参数，但返回异步迭代器：

```python theme={null}
import asyncio
from fetch_hive_sdk import FetchHive

async def main():
    client = FetchHive()
    async for chunk in client.ainvoke_prompt_stream(
        deployment="YOUR_DEPLOYMENT_NAME",
        variant="YOUR_VARIANT_NAME",
        inputs={"text": "Hello"},
    ):
        if chunk.get("type") == "response":
            print(chunk.get("response", ""), end="", flush=True)

asyncio.run(main())
```

## 配置

| 选项         | 默认值                            | 描述               |
| ---------- | ------------------------------ | ---------------- |
| `api_key`  | `FETCH_HIVE_API_KEY` 环境变量      | 来自仪表板的 Bearer 令牌 |
| `base_url` | `https://api.fetchhive.com/v1` | 覆盖 API 基础 URL    |
| `timeout`  | `120`                          | 请求超时（秒）          |

```python theme={null}
client = FetchHive(
    api_key="fhk_...",
    base_url="https://api.fetchhive.com/v1",
    timeout=60,
)
```

## 错误

非 2xx 响应会引发 `httpx.HTTPStatusError`，其中包含状态码和响应体。如需处理失败，请将调用包裹在 `try`/`except` 中：

```python theme={null}
import httpx

try:
    result = client.invoke_prompt(deployment="my-prompt", variant="default")
except httpx.HTTPStatusError as exc:
    print("Fetch Hive returned", exc.response.status_code, exc.response.text)
```

有关状态码含义，请参阅 [错误与速率限制](../api-reference/errors-and-rate-limits)。

## 链接

* [PyPI 上的软件包](https://pypi.org/project/fetch-hive-sdk/)
* [GitHub 上的源码](https://github.com/Fetch-Hive/python-sdk)

## 后续步骤

* [使用 API 运行](./run-with-api) - 使用 cURL 的相同流程
* [使用 Node.js SDK 运行](./run-with-nodejs-sdk)
* [使用 Ruby SDK 运行](./run-with-ruby-sdk)
* [使用 PHP SDK 运行](./run-with-php-sdk)
* [调用提示词](../api-reference/prompts/invoke) - 完整端点参考