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

# 使用 Python SDK 查询日志

> 使用人工智能平台 Python SDK 查询用户日志、系统日志，并下载日志文件。

Python SDK 提供日志查询和下载能力，适用于自动化排查训练任务、通用服务和大模型推理服务的运行问题。使用本文示例前，请先完成 [安装并初始化](https://docs.siflow.cn/ai-platform/developer-access/python-sdk-quickstart.md)。

## 查询用户日志

用户日志来自容器标准输出和标准错误。SDK 提供两类接口：

* `client.logs.query()`：直接按 Pod 名称查询，适合已知 Pod 名称的场景。
* `client.tasks.query_logs()`、`client.generalsvc.query_logs()`、`client.inference.query_logs()`：按业务对象 ID 查询，SDK 自动关联 Pod。

### 按 Pod 查询日志

```python theme={null}
resp = client.logs.query(
    pods=["<POD_NAME>"],
    limit=100,
    offset=0,
    sort_order="asc",
)

print(f"total: {resp.total}")
for item in resp.logs:
    print(f"[{item.time}] [{item.pod_name}] {item.content}")
```

分页查询：

```python theme={null}
resp = client.logs.query(
    pods=["<POD_NAME>"],
    limit=100,
    offset=0,
    sort_order="asc",
)

next_page = client.logs.query(
    pods=["<POD_NAME>"],
    limit=100,
    offset=resp.latest_offset,
    sort_order="asc",
)
```

查询参数如下：

| 参数 | 说明 |
| - | - |
| `pods` | Pod 名称列表。至少包含一个 Pod。 |
| `container` | 容器名称。仅查询单个 Pod 时可指定。 |
| `start` / `end` | 查询起止时间，使用 Unix 时间戳，单位为秒。 |
| `limit` | 每次返回最大条数，单次查询最大 `10000`。 |
| `offset` | 分页偏移量，`offset + limit` 最大 `100000`。 |
| `sort_order` | 排序方式，可选择 `asc` 或 `desc`。返回数据始终按时间正序排列。 |
| `keyword` | 全局关键词搜索，仅返回包含关键词的日志行。空字符串或纯空白等同不传；下载接口不支持关键词搜索。 |

响应字段如下：

| 字段 | 说明 |
| - | - |
| `logs` | 当前页日志列表。 |
| `total` | 匹配的日志总条数。 |
| `latest_offset` | 最新偏移量，可作为下一页的 `offset`。 |
| `LogItem.time` | 日志时间。 |
| `LogItem.pod_name` | Pod 名称。 |
| `LogItem.content` | 日志正文。 |

如果 `pods` 为空，SDK 会抛出 `ValueError`。

### 按业务对象查询日志

按业务对象查询时，SDK 会自动关联该对象下的 Pod。

```python theme={null}
# 训练任务，传入任务 UUID。
task_logs = client.tasks.query_logs(
    "<TASK_UUID>",
    keyword="error",
    limit=100,
    sort_order="asc",
)

# 通用服务，传入通用服务 UUID。
general_service_logs = client.generalsvc.query_logs(
    "<GENERAL_SERVICE_UUID>",
    limit=100,
)

# 大模型推理服务，传入服务 ID。
llm_service_logs = client.inference.query_logs(
    123,
    limit=100,
)
```

高层日志接口参数如下：

| 参数 | 说明 |
| - | - |
| `id` | 业务对象 ID。训练任务和通用服务通常为 UUID 字符串，大模型推理服务为整数 ID。 |
| `start` / `end` | 查询起止时间，使用 Unix 时间戳，单位为秒。不传时，SDK 会根据业务对象和 Pod 信息推断查询范围。 |
| `limit` / `offset` | 分页参数。限制与底层日志查询一致。 |
| `sort_order` | 排序方式，可选择 `asc` 或 `desc`。 |
| `keyword` | 关键词搜索。 |

如果根据业务对象 ID 未关联到 Pod，查询接口返回空日志列表。

### 按时间和关键词查询

```python theme={null}
import time

now = int(time.time())
one_hour_ago = now - 3600

resp = client.tasks.query_logs(
    "<TASK_UUID>",
    keyword="error",
    start=one_hour_ago,
    end=now,
    limit=1000,
    offset=0,
    sort_order="asc",
)

for item in resp.logs:
    print(f"[{item.time}] {item.content}")
```

## 下载用户日志

需要保存排查记录时，可以将日志下载到文件。

### 按业务对象下载

```python theme={null}
file_path = client.tasks.download_logs(
    "<TASK_UUID>",
    file_path="./task.log",
    with_timestamp=True,
    with_pod_name=True,
)

print(file_path)
```

通用服务和大模型推理服务也支持同样的高层下载接口：

```python theme={null}
general_log = client.generalsvc.download_logs(
    "<GENERAL_SERVICE_UUID>",
    file_path="./general-service.log",
)

llm_log = client.inference.download_logs(
    123,
    file_path="./llm-service.log",
)
```

### 按 Pod 流式下载

```python theme={null}
lines = client.logs.download_stream(
    pods=["<POD_NAME>"],
    with_timestamp=True,
    with_pod_name=True,
)

for line in lines:
    print(line)
```

写入文件：

```python theme={null}
file_path = client.logs.download_stream_to_file(
    pods=["<POD_NAME>"],
    file_path="./pod.log",
)

print(file_path)
```

不传 `file_path` 时，SDK 会在当前目录自动生成日志文件名。`file_path` 不能是目录；如果目标文件已存在，应确保文件为空或改用新文件。

下载参数如下：

| 参数 | 说明 |
| - | - |
| `pods` | Pod 名称列表。使用底层接口时必填。 |
| `id` | 业务对象 ID。使用高层接口时传入。 |
| `container` | 容器名称。仅查询单个 Pod 时可指定。 |
| `start` / `end` | 下载起止时间，使用 Unix 时间戳，单位为秒。 |
| `with_timestamp` | 输出中是否包含时间戳。 |
| `with_pod_name` | 输出中是否包含 Pod 名称。 |
| `file_path` | 目标文件路径。不填时自动生成。 |

## 查询系统日志

系统日志来自工作负载 Pod 的 Kubernetes 事件，适合排查调度、拉取镜像、启动、驱逐、OOM 等平台侧问题。它与用户日志不同：用户日志是容器输出，系统日志是 Pod 生命周期事件。

### 按 Pod 查询系统日志

```python theme={null}
resp = client.logs.query_sys_logs(
    pods=["<POD_NAME>"],
)

print(f"total: {resp.total}")
for item in resp.sys_logs:
    print(f"[{item.time}] [{item.pod_name}] {item.type}/{item.name} {item.content}")
```

按时间范围查询：

```python theme={null}
import time

now = int(time.time())
one_hour_ago = now - 3600

resp = client.logs.query_sys_logs(
    pods=["<POD_NAME>"],
    start=one_hour_ago,
    end=now,
)
```

系统日志底层接口参数如下：

| 参数 | 说明 |
| - | - |
| `pods` | Pod 名称列表。至少包含一个非空项。 |
| `start` / `end` | 查询起止时间，使用 Unix 时间戳，单位为秒。 |

系统日志响应字段如下：

| 字段 | 说明 |
| - | - |
| `sys_logs` | 系统日志列表。服务端无数据时为空列表。 |
| `total` | 匹配到的事件总数。 |
| `SysLogItem.time` | 事件首次发生时间。 |
| `SysLogItem.pod_name` | 关联的 Pod 名称。 |
| `SysLogItem.type` | 事件级别，例如 `Warning` 或 `Normal`。 |
| `SysLogItem.name` | 事件名称，例如 `Scheduled` 或 `Evict`。 |
| `SysLogItem.content` | 事件消息内容。 |

### 按业务对象查询系统日志

```python theme={null}
task_sys_logs = client.tasks.query_sys_logs("<TASK_UUID>")
general_sys_logs = client.generalsvc.query_sys_logs("<GENERAL_SERVICE_UUID>")
llm_sys_logs = client.inference.query_sys_logs(123)
```

系统日志高层接口也支持 `start` 和 `end` 参数。如果根据业务对象 ID 未关联到 Pod，接口返回空系统日志列表。

当前系统日志接口不支持按容器、工作负载名称、工作负载类型、关键词、分页或下载查询。

## 请求限制

日志查询与下载接口存在并发和请求次数限制。自动化脚本应控制轮询频率；如果返回请求过多或服务繁忙，请按响应中的重试建议退避后再请求。

| 限制 | 触发情况 | 建议处理 |
| - | - | - |
| 并发限制 | 同一类接口同时处理中的请求数超过服务端上限，错误信息包含 `Concurrent request limit exceeded`。 | 降低并发，短暂退避后重试。 |
| 请求次数限制 | 单位时间窗口内请求次数超限。<ul><li>状态码为 `429 Too Many Requests`。</li><li>错误信息包含 `Rate limit exceeded`。</li></ul> | 按响应中的 `Retry-After` 或 `retryAfter` 等待后重试。 |

## 相关文档

* [Python SDK 快速开始](https://docs.siflow.cn/ai-platform/developer-access/python-sdk-quickstart.md)
* [使用 Python SDK 查询指标](https://docs.siflow.cn/ai-platform/developer-access/query-metrics-with-python-sdk.md)
* [查看训练任务日志](https://docs.siflow.cn/ai-platform/training/view-training-task-logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.