252 lines
5.3 KiB
Markdown
252 lines
5.3 KiB
Markdown
# 快速入门指南
|
||
|
||
本指南帮助算法同学快速上手 FunctionalScaffold 脚手架，在 10 分钟内完成第一个算法服务的开发和部署。
|
||
|
||
## 核心理念
|
||
|
||
**算法同学只需关注核心算法逻辑**，框架自动处理：
|
||
- HTTP 接口封装
|
||
- 参数验证
|
||
- 错误处理
|
||
- 日志记录
|
||
- 性能指标
|
||
- 健康检查
|
||
- 容器化部署
|
||
|
||
## 环境准备
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone <repository-url>
|
||
cd FunctionalScaffold
|
||
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
source venv/bin/activate # Windows: venv\Scripts\activate
|
||
|
||
# 安装依赖
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
### 2. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（自动重载）
|
||
uvicorn src.functional_scaffold.main:app --reload --port 8000
|
||
# docker 开发者模式
|
||
cd deployment && docker compose up -d
|
||
```
|
||
|
||
### 3. 验证服务
|
||
|
||
```bash
|
||
# 健康检查
|
||
curl http://localhost:8000/healthz
|
||
|
||
# 调用示例算法
|
||
curl -X POST http://localhost:8000/invoke \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"number": 17}'
|
||
```
|
||
|
||
## 添加你的第一个算法
|
||
|
||
### 步骤 1：创建算法类
|
||
|
||
在 `src/functional_scaffold/algorithms/` 目录下创建新文件：
|
||
|
||
```python
|
||
# src/functional_scaffold/algorithms/my_algorithm.py
|
||
from typing import Dict, Any
|
||
from .base import BaseAlgorithm
|
||
|
||
class MyAlgorithm(BaseAlgorithm):
|
||
"""我的算法类"""
|
||
|
||
def process(self, input_data: Any) -> Dict[str, Any]:
|
||
"""
|
||
算法处理逻辑 - 只需实现这个方法！
|
||
|
||
Args:
|
||
input_data: 输入数据
|
||
|
||
Returns:
|
||
Dict[str, Any]: 处理结果
|
||
"""
|
||
# 在这里实现你的算法逻辑
|
||
result = self._do_calculation(input_data)
|
||
|
||
return {
|
||
"input": input_data,
|
||
"output": result,
|
||
"message": "处理成功"
|
||
}
|
||
|
||
def _do_calculation(self, data):
|
||
"""内部计算方法"""
|
||
# 你的算法实现
|
||
return data * 2
|
||
```
|
||
|
||
### 步骤 2：注册算法
|
||
|
||
在 `src/functional_scaffold/algorithms/__init__.py` 中添加导出：
|
||
|
||
```python
|
||
from .base import BaseAlgorithm
|
||
from .prime_checker import PrimeChecker
|
||
from .my_algorithm import MyAlgorithm # 添加这行
|
||
|
||
__all__ = ["BaseAlgorithm", "PrimeChecker", "MyAlgorithm"] # 添加到列表
|
||
```
|
||
|
||
### 步骤 3：添加 API 端点
|
||
|
||
在 `src/functional_scaffold/api/routes.py` 中添加路由：
|
||
|
||
```python
|
||
from ..algorithms.my_algorithm import MyAlgorithm
|
||
|
||
@router.post("/my-endpoint")
|
||
async def my_endpoint(
|
||
request: MyRequest, # 需要定义请求模型
|
||
request_id: str = Depends(get_request_id)
|
||
):
|
||
"""我的算法端点"""
|
||
algorithm = MyAlgorithm()
|
||
result = algorithm.execute(request.data)
|
||
|
||
if not result["success"]:
|
||
raise HTTPException(status_code=500, detail=result["error"])
|
||
|
||
return {
|
||
"request_id": request_id,
|
||
"status": "success",
|
||
"result": result["result"],
|
||
"metadata": result["metadata"]
|
||
}
|
||
```
|
||
|
||
### 步骤 4：定义请求模型
|
||
|
||
在 `src/functional_scaffold/api/models.py` 中添加：
|
||
|
||
```python
|
||
class MyRequest(BaseModel):
|
||
"""我的请求模型"""
|
||
|
||
model_config = ConfigDict(
|
||
json_schema_extra={
|
||
"example": {"data": 10}
|
||
}
|
||
)
|
||
|
||
data: int = Field(..., description="输入数据")
|
||
```
|
||
|
||
### 步骤 5：测试
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/my-endpoint \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"data": 10}'
|
||
```
|
||
|
||
## 使用异步任务
|
||
|
||
对于耗时较长的算法，使用异步任务接口：
|
||
|
||
### 创建异步任务
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/jobs \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"algorithm": "MyAlgorithm",
|
||
"params": {"data": 10},
|
||
"webhook": "https://your-callback-url.com/notify"
|
||
}'
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"job_id": "a1b2c3d4e5f6",
|
||
"status": "pending",
|
||
"message": "任务已创建",
|
||
"created_at": "2026-02-02T10:00:00Z"
|
||
}
|
||
```
|
||
|
||
### 查询任务状态
|
||
|
||
```bash
|
||
curl http://localhost:8000/jobs/a1b2c3d4e5f6
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"job_id": "a1b2c3d4e5f6",
|
||
"status": "completed",
|
||
"algorithm": "MyAlgorithm",
|
||
"result": {"input": 10, "output": 20},
|
||
"metadata": {"elapsed_time": 0.001}
|
||
}
|
||
```
|
||
|
||
## 本地开发技巧
|
||
|
||
### 查看 API 文档
|
||
|
||
启动服务后访问：
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest tests/ -v
|
||
|
||
# 运行单个测试文件
|
||
pytest tests/test_algorithms.py -v
|
||
```
|
||
|
||
### 代码格式化
|
||
|
||
```bash
|
||
# 格式化代码
|
||
black src/ tests/
|
||
|
||
# 检查代码规范
|
||
ruff check src/ tests/
|
||
```
|
||
|
||
## 下一步
|
||
|
||
- [算法开发详细指南](./algorithm-development.md) - 深入了解算法开发
|
||
- [API 参考文档](./api-reference.md) - 完整的 API 说明
|
||
- [监控指南](./monitoring.md) - 了解监控和告警
|
||
- [部署指南](./deployment.md) - 生产环境部署
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何处理算法中的异常？
|
||
|
||
A: 在 `process()` 方法中抛出异常即可，框架会自动捕获并返回标准错误响应。
|
||
|
||
### Q: 如何添加自定义指标？
|
||
|
||
A: 在 `config/metrics.yaml` 中定义指标，然后在代码中使用 `incr()` 或 `observe()` 记录。
|
||
|
||
### Q: 如何访问外部服务（数据库、OSS）？
|
||
|
||
A: 在 `config.py` 中添加配置项，通过环境变量注入连接信息。
|
||
|
||
### Q: 算法需要加载大模型文件怎么办？
|
||
|
||
A: 在算法类的 `__init__` 方法中加载模型，框架会在容器启动时初始化。
|