Files

T

CI / build-and-test (push) Has been cancelled

Details

Initial commit: E4B-MarkBase model integration with passing tests

- E4B-MarkBase model (42 layers, 4.4GB) loaded successfully
- All Phase 1-6 tests passed (model loading, forward pass, vision/audio towers, token generation, performance)
- All stress tests passed (5/5 in 127.6s)
  - Concurrent inference
  - Memory stress (67.5 tok/s, 0 NaN)
  - Continuous generation
  - Batch processing
  - Long-running stability
- Swift Metal inference engine with multimodal support

2026-06-23 18:12:35 +08:00

7.7 KiB

Raw Permalink Blame History

MarkBase 完整 API 規劃

📋 API 概述

MarkBase 提供 OpenAI 兼容的 REST API，支持文本生成、多模態推理和流式輸出。

🔌 端點清單

基礎端點

方法	路徑	說明
GET	`/health`	健康檢查
GET	`/v1/models`	模型列表
GET	`/v1/models/{model_id}`	模型詳情

推理端點

方法	路徑	說明
POST	`/v1/chat/completions`	對話生成
POST	`/v1/completions`	文本補全
POST	`/v1/embeddings`	嵌入向量

多模態端點

方法	路徑	說明
POST	`/v1/chat/completions`	圖片理解
POST	`/v1/chat/completions`	音訊理解

📝 詳細 API 規範

GET /health

健康檢查端點

響應:

{
  "status": "healthy",
  "model": "markbase-12b",
  "layers": 48,
  "vocabSize": 262144,
  "version": "1.0.0"
}

GET /v1/models

獲取可用模型列表

響應:

{
  "object": "list",
  "data": [
    {
      "id": "markbase-12b",
      "object": "model",
      "created": 1234567890,
      "owned_by": "markbase",
      "permissions": ["read"],
      "capabilities": {
        "text": true,
        "vision": true,
        "audio": true
      }
    }
  ]
}

POST /v1/chat/completions

對話生成（支持文本、圖片、音訊）

請求體

{
  "model": "markbase-12b",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
            "detail": "high"
          }
        }
      ]
    }
  ],
  "max_tokens": 100,
  "temperature": 0.7,
  "top_p": 0.95,
  "top_k": 40,
  "stream": false,
  "stop": ["\n\n"],
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0
}

參數說明

參數	類型	默認	必填	說明
`model`	string	-	✅	模型 ID
`messages`	array	-	✅	消息列表
`max_tokens`	int	100	❌	最大生成 token 數 (1-4096)
`temperature`	float	1.0	❌	溫度 (0.0-2.0)
`top_p`	float	1.0	❌	核采樣閾值 (0.0-1.0)
`top_k`	int	-	❌	Top-k 采樣
`stream`	bool	false	❌	是否流式輸出
`stop`	array	-	❌	停止序列
`presence_penalty`	float	0.0	❌	存在懲罰 (-2.0-2.0)
`frequency_penalty`	float	0.0	❌	頻率懲罰 (-2.0-2.0)

響應（非流式）

{
  "id": "chatcmpl-abc123def456",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "markbase-12b",
  "system_fingerprint": "fp_markbase",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "This is a beautiful landscape photo...",
        "tool_calls": []
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 50,
    "total_tokens": 200
  }
}

響應（流式）

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"markbase-12b","system_fingerprint":"fp_markbase","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"markbase-12b","system_fingerprint":"fp_markbase","choices":[{"index":0,"delta":{"content":"This"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"markbase-12b","system_fingerprint":"fp_markbase","choices":[{"index":0,"delta":{"content":" is"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1234567890,"model":"markbase-12b","system_fingerprint":"fp_markbase","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

POST /v1/completions

文本補全（舊版 API，建議使用 /v1/chat/completions）

請求體

{
  "model": "markbase-12b",
  "prompt": "Hello, world!",
  "max_tokens": 100,
  "temperature": 0.7,
  "top_p": 0.95,
  "top_k": 40,
  "stream": false,
  "stop": ["\n\n"]
}

響應

{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "created": 1234567890,
  "model": "markbase-12b",
  "choices": [
    {
      "index": 0,
      "text": " How are you today?",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

POST /v1/embeddings

生成嵌入向量

請求體

{
  "model": "markbase-12b",
  "input": "Hello world",
  "encoding_format": "float"
}

響應

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.1, 0.2, 0.3, ...],
      "usage": {
        "prompt_tokens": 5,
        "total_tokens": 5
      }
    }
  ],
  "model": "markbase-12b",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}

🖼️ 多模態格式

圖片輸入

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What's in this image?"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
            "detail": "high"
          }
        }
      ]
    }
  ]
}

支持的格式：

JPEG
PNG
WebP
GIF

大小限制：

最大 20MB
建議 1024x1024 以下

音訊輸入

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Transcribe this audio"},
        {
          "type": "audio_url",
          "audio_url": {
            "url": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA="
          }
        }
      ]
    }
  ]
}