From d7b62df9dfae32c62c2d7ec3da79ab3239af8d31 Mon Sep 17 00:00:00 2001 From: Onur Gündüz Date: Mon, 15 Jun 2026 11:14:44 +0200 Subject: server: add Qwen3 text_type query/document instruction hint --- embed_server.c | 73 ++++++++++++++++++++++++++++++++++++++++-- tests/test_server.c | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 2 deletions(-) diff --git a/embed_server.c b/embed_server.c index 5224282..cf3a9ec 100644 --- a/embed_server.c +++ b/embed_server.c @@ -66,6 +66,13 @@ #define EMBED_LATE_MASK_TOKEN_ID 151642 #define EMBED_LATE_QUERY_PREFIX_ID 151669 #define EMBED_LATE_DOCUMENT_PREFIX_ID 151670 +/* Qwen3/DashScope `text_type: query` prepends this default retrieval instruction + * in the Qwen3-Embedding format ("Instruct: {task}\nQuery:{query}"); documents + * and the default pass through unchanged. The task text matches the + * Qwen3-Embedding reference default; callers needing a custom instruction still + * prepend their own text and leave text_type at "document". */ +#define EMBED_QWEN3_QUERY_INSTRUCT \ + "Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:" /* Chosen from the L4 scheduler sweep: -b 32 gained ~24% concurrent * short-request throughput over 8 with no long-document penalty, while 128 * was no faster and inflated long-document tail latency. */ @@ -1235,6 +1242,35 @@ static const char *encoding_from_root(cJSON *root, cJSON *detail, embedding_api_ return v; } +/* Parse the Qwen3/DashScope `text_type` hint. Returns 1 when the query + * retrieval instruction should be prepended, 0 otherwise (document / absent). + * The field belongs to the OpenAI/DashScope (Qwen3) family only; on a Perplexity + * model it is rejected, since pplx-embed has no instruction concept. Invalid + * values are reported into detail and treated as the no-op default. */ +static int text_type_is_query(cJSON *root, cJSON *detail, embedding_api_t api) { + cJSON *tt = cJSON_GetObjectItemCaseSensitive(root, "text_type"); + if (!tt) + return 0; + if (api != EMBED_API_OPENAI) { + ve_add(detail, "[\"body\",\"text_type\"]", + "text_type is only supported for Qwen3-Embedding models", "extra_fields"); + return 0; + } + if (!cJSON_IsString(tt) || !tt->valuestring) { + ve_add(detail, "[\"body\",\"text_type\"]", "text_type must be a string", + "type_error.string"); + return 0; + } + const char *v = tt->valuestring; + if (!strcmp(v, "query")) + return 1; + if (!strcmp(v, "document")) + return 0; + ve_add(detail, "[\"body\",\"text_type\"]", + "value is not a valid enum member; permitted: 'query', 'document'", "enum"); + return 0; +} + static int dimensions_from_root(cJSON *root, cJSON *detail, int min_dim, int max_dim, const char *encoding) { int dims = max_dim; @@ -1461,6 +1497,28 @@ static int tokenize_one(loaded_model *m, job *j, const char *text, token_buf *ou return 0; } +/* Tokenize one embedding input, prepending the Qwen3 query instruction when + * query_instruct is set. The instruction is part of the text the model sees, so + * it is tokenized in one pass with the input (and the terminal token, if any, is + * appended by tokenize_one as usual). */ +static int +tokenize_input(loaded_model *m, job *j, const char *text, int query_instruct, token_buf *out) { + if (!query_instruct) + return tokenize_one(m, j, text, out); + size_t plen = strlen(EMBED_QWEN3_QUERY_INSTRUCT); + size_t tlen = strlen(text); + char *buf = (char *)malloc(plen + tlen + 1); + if (!buf) { + memset(out, 0, sizeof(*out)); + return -1; + } + memcpy(buf, EMBED_QWEN3_QUERY_INSTRUCT, plen); + memcpy(buf + plen, text, tlen + 1); + int rc = tokenize_one(m, j, buf, out); + free(buf); + return rc; +} + static int late_id_is_skipped(const loaded_model *m, int id) { for (int i = 0; i < m->n_late_skip_ids; i++) { if (m->late_skip_ids[i] == id) @@ -1945,6 +2003,16 @@ static void prepare_embedding_request(job *j, cJSON *root, http_server *s, embed out->dims = dims; out->encoding = encoding; + /* Resolve the API family from the requested model (independent of load + * state) to validate the Qwen3/DashScope text_type hint. query_instruct is + * applied to every input in the request. */ + cJSON *model_item = cJSON_GetObjectItemCaseSensitive(root, "model"); + model_slot api_slot = (model_item && cJSON_IsString(model_item) && model_item->valuestring) + ? model_slot_for_id(model_item->valuestring) + : MODEL_UNKNOWN; + embedding_api_t api = api_slot != MODEL_UNKNOWN ? k_models[api_slot].api : EMBED_API_PERPLEXITY; + int query_instruct = text_type_is_query(root, detail, api); + cJSON *input = cJSON_GetObjectItemCaseSensitive(root, "input"); int n_inputs = 0; if (!input) { @@ -1991,7 +2059,7 @@ static void prepare_embedding_request(job *j, cJSON *root, http_server *s, embed int idx = 0; if (input && cJSON_IsString(input) && input->valuestring) { - if (tokenize_one(m, j, input->valuestring, &out->tokens[0]) != 0) { + if (tokenize_input(m, j, input->valuestring, query_instruct, &out->tokens[0]) != 0) { ve_add(detail, "[\"body\",\"input\"]", "tokenization failed", "value_error.tokenization"); } else { @@ -2012,7 +2080,8 @@ static void prepare_embedding_request(job *j, cJSON *root, http_server *s, embed idx++; continue; } - if (tokenize_one(m, j, item->valuestring, &out->tokens[idx]) != 0) { + if (tokenize_input(m, j, item->valuestring, query_instruct, &out->tokens[idx]) != + 0) { ve_add(detail, loc, "tokenization failed", "value_error.tokenization"); } else { out->inputs[idx].ids = out->tokens[idx].ids; diff --git a/tests/test_server.c b/tests/test_server.c index d799107..ce9668e 100644 --- a/tests/test_server.c +++ b/tests/test_server.c @@ -143,6 +143,44 @@ static void test_encoding_from_root_family(void) { cJSON_Delete(detail); } +static void test_text_type(void) { + cJSON *detail = cJSON_CreateArray(); + + /* Absent: no-op for both families, no error. */ + cJSON *empty = cJSON_CreateObject(); + TEST_ASSERT(text_type_is_query(empty, detail, EMBED_API_OPENAI) == 0); + TEST_ASSERT(text_type_is_query(empty, detail, EMBED_API_PERPLEXITY) == 0); + cJSON_Delete(empty); + TEST_ASSERT(cJSON_GetArraySize(detail) == 0); + + /* Qwen3: query -> 1, document -> 0, both accepted. */ + cJSON *q = cJSON_CreateObject(); + cJSON_AddStringToObject(q, "text_type", "query"); + TEST_ASSERT(text_type_is_query(q, detail, EMBED_API_OPENAI) == 1); + cJSON_Delete(q); + cJSON *d = cJSON_CreateObject(); + cJSON_AddStringToObject(d, "text_type", "document"); + TEST_ASSERT(text_type_is_query(d, detail, EMBED_API_OPENAI) == 0); + cJSON_Delete(d); + TEST_ASSERT(cJSON_GetArraySize(detail) == 0); + + /* Invalid enum value on Qwen3 is reported. */ + cJSON *bad = cJSON_CreateObject(); + cJSON_AddStringToObject(bad, "text_type", "passage"); + TEST_ASSERT(text_type_is_query(bad, detail, EMBED_API_OPENAI) == 0); + TEST_ASSERT(cJSON_GetArraySize(detail) == 1); + cJSON_Delete(bad); + + /* text_type on a Perplexity-family model is rejected. */ + cJSON *p = cJSON_CreateObject(); + cJSON_AddStringToObject(p, "text_type", "query"); + TEST_ASSERT(text_type_is_query(p, detail, EMBED_API_PERPLEXITY) == 0); + TEST_ASSERT(cJSON_GetArraySize(detail) == 2); + cJSON_Delete(p); + + cJSON_Delete(detail); +} + static void test_collect_job_batch_deadline(void) { http_server s; memset(&s, 0, sizeof(s)); @@ -580,6 +618,59 @@ static void test_http_embeddings(int port) { free(body); body = NULL; + /* text_type=query must equal manually prepending the Qwen3 instruction with + * text_type=document: both produce the same tokens, hence the same vector. */ + TEST_ASSERT(http_req(port, "POST", "/v1/embeddings", TEST_API_KEY, + "{\"model\":\"Qwen3-Embedding-0.6B\",\"input\":\"hello\"," + "\"text_type\":\"query\",\"encoding_format\":\"float\"}", + NULL, &body) == 200); + cJSON *tt_query = body ? parse_embeddings_body(body, 1) : NULL; + free(body); + body = NULL; + TEST_ASSERT(http_req(port, "POST", "/v1/embeddings", TEST_API_KEY, + "{\"model\":\"Qwen3-Embedding-0.6B\",\"input\":\"Instruct: Given a web " + "search query, retrieve relevant passages that answer the " + "query\\nQuery:hello\",\"text_type\":\"document\"," + "\"encoding_format\":\"float\"}", + NULL, &body) == 200); + cJSON *tt_manual = body ? parse_embeddings_body(body, 1) : NULL; + free(body); + body = NULL; + if (tt_query && tt_manual) { + cJSON *qe = cJSON_GetObjectItemCaseSensitive( + cJSON_GetArrayItem(cJSON_GetObjectItemCaseSensitive(tt_query, "data"), 0), "embedding"); + cJSON *me = cJSON_GetObjectItemCaseSensitive( + cJSON_GetArrayItem(cJSON_GetObjectItemCaseSensitive(tt_manual, "data"), 0), + "embedding"); + TEST_ASSERT(cJSON_IsArray(qe) && cJSON_IsArray(me) && + cJSON_GetArraySize(qe) == cJSON_GetArraySize(me)); + double tt_diff = 0.0; + int n = cJSON_GetArraySize(qe); + for (int i = 0; i < n; i++) { + double d = fabs(cJSON_GetArrayItem(qe, i)->valuedouble - + cJSON_GetArrayItem(me, i)->valuedouble); + if (d > tt_diff) + tt_diff = d; + } + TEST_ASSERT(tt_diff < 1e-6); + } + cJSON_Delete(tt_query); + cJSON_Delete(tt_manual); + + /* text_type is rejected on a Perplexity-family model, and bad values 422. */ + TEST_ASSERT(http_req(port, "POST", "/v1/embeddings", TEST_API_KEY, + "{\"model\":\"pplx-embed-v1-0.6b\",\"input\":\"hello\"," + "\"text_type\":\"query\"}", + NULL, &body) == 422); + free(body); + body = NULL; + TEST_ASSERT(http_req(port, "POST", "/v1/embeddings", TEST_API_KEY, + "{\"model\":\"Qwen3-Embedding-0.6B\",\"input\":\"hello\"," + "\"text_type\":\"passage\"}", + NULL, &body) == 422); + free(body); + body = NULL; + /* Concurrent clients: more requests in flight than the micro-batch cap * (-b 2) so the worker has to assemble several batches. */ enum { N_CONC = 6 }; @@ -900,6 +991,7 @@ int main(void) { test_encode_embedding_base64_float32(); test_append_embedding_value_float(); test_encoding_from_root_family(); + test_text_type(); test_collect_job_batch_deadline(); test_collect_job_batch_zero_wait(); test_http_server(); -- cgit v1.3.1