diff options
Diffstat (limited to 'devtools/openapi.yaml')
| -rw-r--r-- | devtools/openapi.yaml | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/devtools/openapi.yaml b/devtools/openapi.yaml new file mode 100644 index 0000000..5140186 --- /dev/null +++ b/devtools/openapi.yaml @@ -0,0 +1,249 @@ +openapi: 3.0.3 +info: + title: ffwd server API + version: "1.0.0" + description: > + HTTP API served by `ffwd-server`. Each loaded model has an operator-chosen + label; request `model` fields match that label. Embedding encoding follows + the serving API selected at load time (`api=openai` or `api=perplexity`). + Always compare embeddings with cosine similarity. + license: + name: MIT +servers: + - url: http://127.0.0.1:8000 +# Auth is optional: it applies only when the server is started with --api-key +# (or FFWD_API_KEY). The empty requirement allows unauthenticated calls. +security: + - {} + - bearerAuth: [] +paths: + /v1/embeddings: + post: + summary: Create pooled embeddings + operationId: createEmbeddings + requestBody: + required: true + content: + application/json: + schema: { $ref: "#/components/schemas/EmbeddingsRequest" } + responses: + "200": + description: One embedding per input, in request order. + content: + application/json: + schema: { $ref: "#/components/schemas/EmbeddingsResponse" } + "422": { $ref: "#/components/responses/ValidationError" } + /v1/contextualizedembeddings: + post: + summary: Create contextual (late-chunking) document embeddings + operationId: createContextualizedEmbeddings + description: > + Each document is a list of chunk strings. Chunks are embedded with + document-level context and returned per document, per chunk, in order. + requestBody: + required: true + content: + application/json: + schema: { $ref: "#/components/schemas/ContextualRequest" } + responses: + "200": + description: One list of chunk embeddings per document, in order. + content: + application/json: + schema: { $ref: "#/components/schemas/ContextualResponse" } + "422": { $ref: "#/components/responses/ValidationError" } + /v1/rerank: + post: + summary: Late-interaction (MaxSim) reranking + operationId: rerank + description: > + Scores each document against the query with token-level MaxSim and + returns documents ranked by raw score (not a probability). + requestBody: + required: true + content: + application/json: + schema: { $ref: "#/components/schemas/RerankRequest" } + responses: + "200": + description: Documents ranked by descending relevance score. + content: + application/json: + schema: { $ref: "#/components/schemas/RerankResponse" } + "422": { $ref: "#/components/responses/ValidationError" } +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + description: > + Single shared token set with --api-key. Not a real auth system; + terminate TLS and authenticate at a reverse proxy in production. + schemas: + EmbeddingsRequest: + type: object + required: [model, input] + properties: + model: + type: string + description: Served label chosen when starting `ffwd-server`. + example: qwen + input: + description: A single string or an array of up to 512 strings. + oneOf: + - type: string + - type: array + items: { type: string } + minItems: 1 + maxItems: 512 + encoding_format: + type: string + description: > + Output encoding, validated against the serving API selected for the + loaded label. `api=openai` accepts `float` (default; true float32) + and `base64` (base64 of little-endian float32). `api=perplexity` + accepts `base64_int8` (default), `base64_binary` (sign bits, needs + `dimensions` divisible by 8), and `float` (the int8-decoded view). + A format outside the label's serving API returns 422. + enum: [float, base64, base64_int8, base64_binary] + dimensions: + type: integer + description: > + Matryoshka truncation, from the configured load-time `min_dim` up to + the model's native dimension. Truncated normalized vectors are + re-normalized. + EmbeddingsResponse: + type: object + properties: + object: { type: string, example: list } + data: + type: array + items: { $ref: "#/components/schemas/Embedding" } + model: { type: string } + usage: { $ref: "#/components/schemas/Usage" } + Embedding: + type: object + properties: + object: { type: string, example: embedding } + index: { type: integer } + embedding: + description: > + A float array when `encoding_format` is `float`, otherwise a base64 + string (`base64`, `base64_int8`, or `base64_binary`). + oneOf: + - type: array + items: { type: number, format: float } + - type: string + ContextualRequest: + type: object + required: [model, input] + properties: + model: + type: string + description: Served contextual-model label. + example: pplx-context + input: + description: Array of documents; each document is an array of chunk strings. + type: array + items: + type: array + items: { type: string } + minItems: 1 + encoding_format: + type: string + enum: [float, base64, base64_int8, base64_binary] + dimensions: { type: integer } + ContextualResponse: + type: object + properties: + object: { type: string, example: list } + data: + type: array + description: One entry per document, in request order. + items: + type: object + properties: + object: { type: string, example: list } + index: { type: integer } + data: + type: array + description: One embedding per chunk, in document order. + items: { $ref: "#/components/schemas/Embedding" } + model: { type: string } + usage: { $ref: "#/components/schemas/Usage" } + RerankRequest: + type: object + required: [model, query, documents] + properties: + model: + type: string + description: Served late-model label. + example: pplx-late + query: { type: string } + documents: + type: array + items: { type: string } + minItems: 1 + maxItems: 1000 + top_n: + type: integer + description: Number of results to return. Defaults to all. `top_k` is an alias. + top_k: + type: integer + return_documents: + type: boolean + default: false + description: Include the source document text in each result. + additionalProperties: false + RerankResponse: + type: object + properties: + object: { type: string, example: list } + model: { type: string } + results: + type: array + items: + type: object + properties: + index: + type: integer + description: Index of the document in the request array. + relevance_score: + type: number + format: float + description: Raw MaxSim score (not a probability). + document: + type: string + description: Present only when `return_documents` is true. + usage: + type: object + properties: + query_tokens: { type: integer } + document_tokens: { type: integer } + total_tokens: { type: integer } + Usage: + type: object + properties: + prompt_tokens: { type: integer } + total_tokens: { type: integer } + ValidationDetail: + type: object + properties: + loc: + type: array + description: Path to the offending field, e.g. ["body","input",0]. + items: {} + msg: { type: string } + type: { type: string } + ValidationError: + type: object + properties: + detail: + type: array + items: { $ref: "#/components/schemas/ValidationDetail" } + responses: + ValidationError: + description: Request body failed validation. + content: + application/json: + schema: { $ref: "#/components/schemas/ValidationError" } |
