使用说明
TUNDR MCP Optimization Server
一种高性能优化服务器,实现用于数学优化任务的模型上下文协议(MCP),重点是使用高斯过程的贝叶斯优化。专为生产环境中的可靠性、可扩展性和易集成性而设计。
🌟 特性
🎯 主要特点
贝叶斯优化
- 多核支持(Matern 5/2、RBF、自定义)
- 多点并行评估
- 约束优化支持
- 昂贵黑盒函数的高效全局优化
真实世界用例
-
超参数调整
- 用最少的试验优化机器学习模型超参数
- 支持连续参数和分类参数
- 非常适合深度学习、XGBoost和其他ML框架
-
工程设计优化
- 优化具有多个竞争目标的产品设计
- 处理物理和操作限制
- 在航空航天、汽车和制造业中的应用
-
科学研究
- 优化化学和物理实验参数
- 在计算成本高昂的模拟中最小化成本函数评估
- 适应性实验设计
-
财务模型
- 约束下的投资组合优化
- 算法交易参数优化
- 风险管理参数调整
-
工业过程优化
- 优化制造流程
- 能耗最小化
- 生产线产量提高
- 预期改进获取功能(支持改进概率和UCB)
- 支持最小化和最大化问题
- 多点并行评估
- 约束优化支持
- 符合MCP的API端点
🛠️ 稳健的实施
- 全面的测试覆盖率
- 优雅的错误处理和恢复
- 详细的结构化日志记录 快速攻击
- 上下文感知取消和超时
- 内存高效的矩阵运算
- MCP协议合规性
🚀 性能优化
- 快速矩阵运算 根
- 通过对象池实现高效的内存管理
- 优化Cholesky分解并回退到SVD
- 并行批量预测
📊 监测和可观察性
- Prometheus指标端点
- JSON格式的结构化日志记录
- 分布式跟踪支持(OpenTetry)
- 健康检查端点
- 性能分析端点
特性
-
贝叶斯优化 高斯过程
- 多核支持(Matern 5/2,RBF)
- 预期改进获取功能
- Cholesky分解和SVD回退的数值稳定性
- 支持最小化和最大化问题
- 多点并行评估
-
稳健的实施
- 综合测试覆盖率(>85%)
- 优雅的错误处理和恢复
- 结构化日志记录(zap)的详细日志记录
- 上下文感知取消
-
API与集成
- HTTP/2接口上的JSON-RPC 2.0
- 用于常见操作的RESTful端点
- OpenAPI 3.0文档
- gRPC支持(计划中)
-
监测和可观察性
- Prometheus指标端点
- 结构化日志记录
- 分布式跟踪(OpenTetry)
- 健康检查
-
可扩展性
- 无状态设计
- 水平缩放支持
- 多个存储后端(SQLite、PostgreSQL)
- 缓存层(Redis)
🚀 快速开始
MCP协议支持
此服务器实现了用于优化任务的模型上下文协议(MCP)。MCP提供了一种标准化的方法来:
- 定义优化问题
- 提交优化任务
- 监控优化进度
- 检索优化结果
服务器公开了与MCP兼容的端点,以便与其他符合MCP的工具和服务无缝集成。
先决条件
- 转到1.21或更高版本
- Git(用于版本控制)
- Make(用于开发任务)
- (可选)Docker和Docker Compose用于容器化部署
安装
# Clone the repository
git clone https://github.com/copyleftdev/TUNDR.git
cd TUNDR
# Install dependencies
go mod download
# Build the server
go build -o bin/server ./cmd/server
运行服务器
# Start the server with default configuration
./bin/server
# Or with custom configuration
CONFIG_FILE=config/local.yaml ./bin/server
使用Docker
# Build the Docker image
docker build -t tundr/mcp-optimization-server .
# Run the container
docker run -p 8080:8080 tundr/mcp-optimization-server
📚 文档
MCP集成
服务器实现了以下MCP兼容端点:
REST API
POST /api/v1/optimize-提交新的优化任务GET /api/v1/status/{id}-检查优化任务的状态DELETE /api/v1/optimization/{id}-取消正在运行的优化任务
JSON-RPC 2.0端点
POST /rpc-所有JSON-RPC 2.0操作的统一端点
可用的JSON-RPC方法
-
optimization.start-开始新的优化{ "jsonrpc": "2.0", "id": 1, "method": "optimization.start", "params": [{ "objective": "minimize", "parameters": [ {"name": "x", "type": "float", "bounds": [0, 10]}, {"name": "y", "type": "float", "bounds": [0, 10]} ] }] } -
optimization.status-获取优化状态{ "jsonrpc": "2.0", "id": 2, "method": "optimization.status", "params": ["optimization_id"] } -
optimization.cancel-取消优化{ "jsonrpc": "2.0", "id": 3, "method": "optimization.cancel", "params": ["optimization_id"] }
错误响应
所有端点都以以下格式返回错误:
REST API
{
"error": {
"code": 400,
"message": "Invalid input parameters"
}
}
JSON-RPC 2.0
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Invalid params"
}
}
常见错误代码:
-32600-无效请求-32601-未找到方法-32602-无效参数-32603-内部错误-32000向-32099-服务器错误
api参考
看看 API文档 有关可用方法和类型的详细信息。
示例:基本用法
package main
import (
"context"
"fmt"
"math"
"github.com/copyleftdev/TUNDR/internal/optimization"
"github.com/copyleftdev/TUNDR/internal/optimization/bayesian"
)
func main() {
// Define the objective function (to be minimized)
objective := func(x []float64) (float64, error) {
// Example: Rosenbrock function
return math.Pow(1-x[0], 2) + 100*math.Pow(x[1]-x[0]*x[0], 2), nil
}
// Define parameter bounds
bounds := [][2]float64{{-5, 5}, {-5, 5}}
// Create optimizer configuration
config := optimization.OptimizerConfig{
Objective: objective,
Bounds: bounds,
MaxIterations: 50,
NInitialPoints: 10,
}
// Create and run the optimizer
optimizer, err := bayesian.NewBayesianOptimizer(config)
if err != nil {
panic(fmt.Sprintf("Failed to create optimizer: %v", err))
}
// Run the optimization
result, err := optimizer.Optimize(context.Background(), config)
if err != nil {
panic(fmt.Sprintf("Optimization failed: %v", err))
}
// Print results
fmt.Printf("Optimal parameters: %v\n", result.BestSolution.Parameters)
fmt.Printf("Optimal value: %f\n", result.BestSolution.Value)
fmt.Printf("Number of iterations: %d\n", result.Iterations)
fmt.Printf("Converged: %v\n", result.Converged)
}
配置
创建一个 config.yaml 文件以自定义服务器行为:
server:
port: 8080
env: development
timeout: 30s
logging:
level: info
format: json
output: stdout
optimization:
max_concurrent: 4
default_kernel: "matern52"
default_acquisition: "ei"
storage:
type: "memory" # or "postgres"
dsn: "" # Only needed for postgres
metrics:
enabled: true
path: "/metrics"
namespace: "tundr"
tracing:
enabled: false
service_name: "mcp-optimization-server"
endpoint: "localhost:4317"
🧪 测试
运行测试套件:
# Run all tests
go test ./...
# Run tests with coverage
go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
# Run benchmarks
go test -bench=. -benchmem ./...
🤝 贡献
欢迎投稿!请阅读我们的 贡献指南 有关如何提交pull请求、报告问题或建议新功能的详细信息。
📄 许可证
此项目是CopyleftDev生态系统的一部分,并根据GNU Affero通用公共许可证v3.0获得许可-请参阅 许可证 文件以获取详细信息。
📚 资源
📬 联系
如有疑问或支持,请打开问题或通过[email protected]联系维护人员
安装
-
克隆存储库:
git clone https://github.com/tundr/mcp-optimization-server.git cd mcp-optimization-server -
安装依赖项:
make deps -
构建二进制文件:
make build这将创建一个
tundr二进制在bin目录。
配置
环境变量
创建一个 .env 项目根目录中的文件,包含以下变量:
# Application
ENV=development
LOG_LEVEL=info
HTTP_PORT=8080
# Database
DB_TYPE=sqlite # sqlite or postgres
DB_DSN=file:data/tundr.db?cache=shared&_fk=1
# Authentication
JWT_KEY=your-secure-key-change-in-production
# Optimization
MAX_CONCURRENT_JOBS=10
JOB_TIMEOUT=30m
# Monitoring
METRICS_ENABLED=true
METRICS_PORT=9090
配置文件
对于更复杂的配置,您可以使用YAML配置文件(默认值: config/config.yaml):
server:
env: development
port: 8080
shutdown_timeout: 30s
database:
type: sqlite
dsn: file:data/tundr.db?cache=shared&_fk=1
max_open_conns: 25
max_idle_conns: 5
conn_max_lifetime: 5m
optimization:
max_concurrent_jobs: 10
job_timeout: 30m
default_algorithm: bayesian
bayesian:
default_kernel: matern52
default_noise: 1e-6
max_observations: 1000
cma_es:
population_size: auto # auto or number
max_generations: 1000
monitoring:
metrics:
enabled: true
port: 9090
path: /metrics
tracing:
enabled: false
endpoint: localhost:4317
sample_rate: 0.1
logging:
level: info
format: json
enable_caller: true
enable_stacktrace: true
运行服务器
发展模式
对于热重载开发:
make dev
生产模式
构建并运行服务器:
make build
./bin/tundr serve --config config/production.yaml
使用Docker
# Build the Docker image
docker build -t tundr-optimization .
# Run the container
docker run -p 8080:8080 -v $(pwd)/data:/app/data tundr-optimization
服务器将在以下时间可用 http://localhost:8080
使用示例
贝叶斯优化示例
package main
import (
"context"
"fmt"
"log"
"math"
"github.com/tundr/mcp-optimization-server/internal/optimization"
"github.com/tundr/mcp-optimization-server/internal/optimization/bayesian"
"github.com/tundr/mcp-optimization-server/internal/optimization/kernels"
)
func main() {
// Define the objective function (to be minimized)
objective := func(x []float64) (float64, error) {
// Example: Rosenbrock function
return math.Pow(1-x[0], 2) + 100*math.Pow(x[1]-x[0]*x[0], 2), nil
}
// Define parameter bounds
bounds := []optimization.Parameter{
{Name: "x1", Min: -5.0, Max: 10.0},
{Name: "x2", Min: -5.0, Max: 10.0},
}
// Create optimizer configuration
config := optimization.OptimizerConfig{
Objective: objective,
Parameters: bounds,
NInitialPoints: 10,
MaxIterations: 50,
Verbose: true,
}
// Create and configure the optimizer
optimizer, err := bayesian.NewBayesianOptimizer(config)
if err != nil {
log.Fatalf("Failed to create optimizer: %v", err)
}
// Run the optimization
result, err := optimizer.Optimize(context.Background())
if err != nil {
log.Fatalf("Optimization failed: %v", err)
}
// Print results
fmt.Printf("Best solution: %+v\n", result.BestSolution)
fmt.Printf("Best value: %f\n", result.BestSolution.Value)
fmt.Printf("Number of iterations: %d\n", len(result.History))
}
REST API示例
启动新的优化作业:
curl -X POST http://localhost:8080/api/v1/optimize \
-H "Content-Type: application/json" \
-d '{
"algorithm": "bayesian",
"objective": "minimize",
"parameters": [
{"name": "x1", "type": "float", "bounds": [-5.0, 10.0]},
{"name": "x2", "type": "float", "bounds": [-5.0, 10.0]}
],
"max_iterations": 100,
"n_initial_points": 20,
"metadata": {
"name": "rosenbrock-optimization",
"tags": ["test", "demo"]
}
}'
检查优化状态:
curl http://localhost:8080/api/v1/status/<job_id>
配置参考
贝叶斯优化参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| kernel | string | “matern52” | 内核类型(“matern 52”或“rbf”) |
| length_scale | float | 1.0 | 长度比例参数 |
| 噪声 | 浮动 | 1e-6 | 观测噪声 |
| xi | 浮动 | 0.01 | 勘探开发权衡 |
| n_initial_points | int | 10 | 初始随机点数 |
| max_iteractions | int | 100 | 最大迭代次数 |
| random_sed | int | 0 | 随机种子(0表示基于时间) |
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| ENV | 开发 | 应用环境 |
| LOGLEVEL | 信息 | 日志记录级别 |
| HTTP_PORT | 8080 | HTTP服务器端口 |
| DB_TYPE | sqlite | 数据库类型(sqlite或postgres) |
| DB_DSN | 文件:data/tundr.DB | 数据库连接字符串 |
| JWT_KEY | JWT身份验证密钥 | |
| MAX_CONCURRENT_JOBS | 10 | 最大并发优化作业数 |
| 作业超时 | 30m | 最长作业持续时间 |
| METRIC_ENABLED | true | 启用普罗米修斯指标 |
| METRICS_PORT | 9090 | 度量服务器端口 |
高级用法
自定义内核
您可以通过实现以下命令来实现自定义内核函数 kernels.Kernel 接口:
type Kernel interface {
Eval(x, y []float64) float64
Hyperparameters() []float64
SetHyperparameters(params []float64) error
Bounds() [][2]float64
}
自定义内核示例:
type MyCustomKernel struct {
lengthScale float64
variance float64
}
func (k *MyCustomKernel) Eval(x, y []float64) float64 {
// Implement your custom kernel function
sumSq := 0.0
for i := range x {
diff := x[i] - y[i]
sumSq += diff * diff
}
return k.variance * math.Exp(-0.5*sumSq/(k.lengthScale*k.lengthScale))
}
// Implement other required methods...
平行评估
优化器支持对多个点进行并行评估:
config := optimization.OptimizerConfig{
Objective: objective,
Parameters: bounds,
NInitialPoints: 10,
MaxIterations: 50,
NJobs: 4, // Use 4 parallel workers
}
回调
您可以注册回调来监控优化过程:
optimizer := bayesian.NewBayesianOptimizer(config)
// Add a callback that's called after each iteration
optimizer.AddCallback(func(result *optimization.OptimizationResult) {
fmt.Printf("Iteration %d: Best value = %f\n",
len(result.History),
result.BestSolution.Value)
})
API文档
REST API
开始优化
POST /api/v1/optimize
Content-Type: application/json
{
"algorithm": "bayesian",
"objective": "minimize",
"parameters": [
{"name": "x", "type": "float", "bounds": [0, 10], "prior": "uniform"},
{"name": "y", "type": "float", "bounds": [-5, 5], "prior": "normal", "mu": 0, "sigma": 1}
],
"constraints": [
{"type": "ineq", "expr": "x + y <= 10"}
],
"options": {
"max_iterations": 100,
"n_initial_points": 20,
"acquisition": "ei",
"xi": 0.01,
"kappa": 0.1
},
"metadata": {
"name": "example-optimization",
"tags": ["test"],
"user_id": "user123"
}
}
获取优化状态
GET /api/v1/status/:id
答复:
{
"id": "job-123",
"status": "running",
"progress": 0.45,
"best_solution": {
"parameters": {"x": 1.2, "y": 3.4},
"value": 0.123
},
"start_time": "2025-06-30T10:00:00Z",
"elapsed_time": "1h23m45s",
"iterations": 45,
"metadata": {
"name": "example-optimization",
"tags": ["test"]
}
}
JSON-RPC 2.0 API
服务器还支持JSON-RPC 2.0用于更高级的用例:
POST /rpc
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "optimization.start",
"params": [
{
"algorithm": "bayesian",
"objective": "minimize",
"parameters": [
{"name": "x", "type": "float", "bounds": [0, 10]},
{"name": "y", "type": "float", "bounds": [-5, 5]}
],
"options": {
"max_iterations": 100,
"n_initial_points": 20,
"acquisition": "ei",
"xi": 0.01
}
}
]
}
性能调整
内存使用
对于大规模问题,您可能需要调整以下参数:
- 批量大小:批量处理点以限制内存使用
- GP型号:对大型数据集(>1000个点)使用稀疏近似值
- Cholesky分解:默认解算器使用Cholesky分解和SVD回退
并行性
您可以控制并行工作者的数量:
config := optimization.OptimizerConfig{
// ... other options ...
NJobs: runtime.NumCPU(), // Use all available CPUs
}
缓存
启用内核矩阵计算的缓存:
kernel := kernels.NewMatern52Kernel(1.0, 1.0)
kernel.EnableCache(true) // Enable kernel cache
监测和可观察性
服务器在以下位置公开Prometheus指标 /metrics:
optimization_requests_total:优化请求总数optimization_duration_seconds:优化作业的持续时间optimization_iterations_total:每次优化的迭代次数optimization_errors_total:优化错误数gp_fit_duration_seconds:GP模型拟合持续时间acquisition_evaluations_total:采购职能评估次数
日志记录
默认情况下,日志的结构为JSON格式。以下日志级别可用:
debug:详细的调试信息info:一般操作信息warn:非关键问题error:严重错误
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
开发工作流程
# Run tests
make test
# Run linters
make lint
# Run benchmarks
make benchmark
# Format code
make fmt
# Generate documentation
make docs
许可证
Apache 2.0-请参阅 许可证 了解详情。
致谢
发展
建筑
make build
测试
make test
代码检查
make lint
部署
码头工人
docker build -t tundr/mcp-optimization-server .
docker run -p 8080:8080 --env-file .env tundr/mcp-optimization-server
Kubernetes
请参阅 deploy/kubernetes 目录,例如Kubernetes清单。