130 lines
2.6 KiB
Markdown
130 lines
2.6 KiB
Markdown
# Platform SDK
|
||
|
||
平台基础设施客户端SDK，提供统一的统计上报、日志记录、链路追踪等功能。
|
||
|
||
## 安装
|
||
|
||
SDK作为共享模块使用，通过软链接引用：
|
||
|
||
```bash
|
||
# 在 _shared 目录创建软链接
|
||
cd AgentWD/_shared
|
||
ln -s ../projects/000-platform/sdk platform
|
||
```
|
||
|
||
## 在项目中使用
|
||
|
||
### 1. 添加路径
|
||
|
||
在项目的 `main.py` 开头添加：
|
||
|
||
```python
|
||
import sys
|
||
from pathlib import Path
|
||
|
||
# 添加 _shared 到路径
|
||
sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent.parent / "_shared"))
|
||
|
||
from platform import get_logger, StatsClient, LoggingMiddleware
|
||
```
|
||
|
||
### 2. 日志
|
||
|
||
```python
|
||
from platform import get_logger
|
||
|
||
logger = get_logger("011-ai-interview")
|
||
|
||
# 基础日志
|
||
logger.info("用户开始面试", user_id=123)
|
||
logger.error("面试出错", error=e)
|
||
|
||
# 审计日志
|
||
logger.audit("create", "interview", "123", operator="admin")
|
||
```
|
||
|
||
### 3. AI统计上报
|
||
|
||
```python
|
||
from platform import StatsClient
|
||
|
||
stats = StatsClient(tenant_id=1, app_code="011-ai-interview")
|
||
|
||
# 上报AI调用
|
||
stats.report_ai_call(
|
||
module_code="interview",
|
||
prompt_name="generate_question",
|
||
model="gpt-4",
|
||
input_tokens=100,
|
||
output_tokens=200,
|
||
latency_ms=1500
|
||
)
|
||
```
|
||
|
||
### 4. 链路追踪
|
||
|
||
```python
|
||
from platform import TraceContext, get_trace_id
|
||
|
||
# 在请求处理中
|
||
with TraceContext(tenant_id=1, user_id=100) as ctx:
|
||
print(f"当前trace_id: {ctx.trace_id}")
|
||
# 所有操作共享同一个trace_id
|
||
```
|
||
|
||
### 5. FastAPI中间件
|
||
|
||
```python
|
||
from fastapi import FastAPI
|
||
from platform import LoggingMiddleware, TraceMiddleware
|
||
|
||
app = FastAPI()
|
||
|
||
# 添加中间件（顺序重要）
|
||
app.add_middleware(LoggingMiddleware, app_code="011-ai-interview")
|
||
app.add_middleware(TraceMiddleware)
|
||
```
|
||
|
||
### 6. HTTP客户端
|
||
|
||
```python
|
||
from platform import PlatformHttpClient
|
||
|
||
client = PlatformHttpClient(base_url="https://api.example.com")
|
||
|
||
# 自动传递trace_id和API Key
|
||
response = await client.get("/users/1")
|
||
```
|
||
|
||
### 7. 配置读取
|
||
|
||
```python
|
||
from platform import ConfigReader
|
||
|
||
config = ConfigReader(tenant_id=1)
|
||
|
||
# 读取平台配置
|
||
app_id = await config.get("wechat", "app_id")
|
||
|
||
# 读取环境变量
|
||
debug = config.get_env("DEBUG", False)
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
SDK使用以下环境变量：
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `PLATFORM_URL` | 平台服务地址 | - |
|
||
| `PLATFORM_API_KEY` | 平台API Key | - |
|
||
|
||
## 更新日志
|
||
|
||
### v0.1.0
|
||
|
||
- 初始版本
|
||
- 支持日志、统计、链路追踪
|
||
- 支持FastAPI中间件
|
||
- 支持配置读取
|