Synthesis API Reference
合成数据引擎、同步预览、异步生成 job 和结果读取接口。
Synthesis 可生成结构化记录、关系数据、RAG goldens、QA pairs、对话、agent trajectories 或自定义产物。下面的 API 示例以 AI 生成的 Python、JavaScript 和 Java 客户端代码展示。
| 方法 | 路径 | Scope | 作用 |
|---|---|---|---|
GET | /v1/synthesis/engines | synthesis:read | 列出合成引擎和支持类型。 |
POST | /v1/synthesis/sync | synthesis:write | 生成小规模同步预览。 |
POST | /v1/synthesis/jobs | synthesis:write | 提交异步生成 job。 |
GET | /v1/synthesis/jobs/{jobId}/result | synthesis:read | 读取生成输出和 quality gates。 |
POST | /v1/synthesis/jobs/{jobId}/result | synthesis:write | Worker-side 结果持久化回调。 |
引擎
import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers(): return {"Authorization": f"Bearer {TOKEN}"}response = requests.get(f"{BASE_URL}/v1/synthesis/engines", headers=auth_headers())response.raise_for_status()data = response.json()print(data)const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = { Authorization: `Bearer ${TOKEN}`,};const response = await fetch(`${BASE_URL}/v1/synthesis/engines`, { headers: authHeaders,});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample { static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080"); static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token"); static final HttpClient HTTP = HttpClient.newHttpClient(); static void print(HttpResponse<String> response) { System.out.println(response.statusCode()); System.out.println(response.body()); } public static void main(String[] args) throws Exception { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(BASE_URL + "/v1/synthesis/engines")) .header("Authorization", "Bearer " + TOKEN) .GET() .build(); print(HTTP.send(request, HttpResponse.BodyHandlers.ofString())); }}结构化单表请求
import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers(): return {"Authorization": f"Bearer {TOKEN}"}payload = { "name": "quickstart-sdv-customers", "synthesis_type": "structured_single_table", "engine_id": "sdv", "source": { "type": "inline_records", "inline_records": [ { "customer_id": "c1", "tier": "gold", "monthly_spend": 1200 }, { "customer_id": "c2", "tier": "silver", "monthly_spend": 300 } ], "options": { "table_name": "customers" } }, "config": { "sample_count": 5, "anonymize_pii": True }, "output": { "output_format": "json", "include_preview": True }}response = requests.post( f"{BASE_URL}/v1/synthesis/sync", headers={**auth_headers(), "Content-Type": "application/json"}, json=payload,)response.raise_for_status()data = response.json()print(data)const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = { Authorization: `Bearer ${TOKEN}`,};const payload = { "name": "quickstart-sdv-customers", "synthesis_type": "structured_single_table", "engine_id": "sdv", "source": { "type": "inline_records", "inline_records": [ { "customer_id": "c1", "tier": "gold", "monthly_spend": 1200 }, { "customer_id": "c2", "tier": "silver", "monthly_spend": 300 } ], "options": { "table_name": "customers" } }, "config": { "sample_count": 5, "anonymize_pii": true }, "output": { "output_format": "json", "include_preview": true }};const response = await fetch(`${BASE_URL}/v1/synthesis/sync`, { method: "POST", headers: { ...authHeaders, "Content-Type": "application/json" }, body: JSON.stringify(payload),});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample { static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080"); static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token"); static final HttpClient HTTP = HttpClient.newHttpClient(); static void print(HttpResponse<String> response) { System.out.println(response.statusCode()); System.out.println(response.body()); } public static void main(String[] args) throws Exception { String json = """ { \"name\": \"quickstart-sdv-customers\", \"synthesis_type\": \"structured_single_table\", \"engine_id\": \"sdv\", \"source\": { \"type\": \"inline_records\", \"inline_records\": [ { \"customer_id\": \"c1\", \"tier\": \"gold\", \"monthly_spend\": 1200 }, { \"customer_id\": \"c2\", \"tier\": \"silver\", \"monthly_spend\": 300 } ], \"options\": { \"table_name\": \"customers\" } }, \"config\": { \"sample_count\": 5, \"anonymize_pii\": true }, \"output\": { \"output_format\": \"json\", \"include_preview\": true } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(BASE_URL + "/v1/synthesis/sync")) .header("Authorization", "Bearer " + TOKEN) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); print(HTTP.send(request, HttpResponse.BodyHandlers.ofString())); }}非结构化 QA 请求
import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers(): return {"Authorization": f"Bearer {TOKEN}"}payload = { "name": "quickstart-qa-preview", "synthesis_type": "qa_pairs", "engine_id": "deepeval", "source": { "type": "documents", "documents": [ "Cortex Parse turns URLs and storage objects into LLM-ready Markdown." ] }, "config": { "sample_count": 2, "max_contexts_per_case": 1, "include_expected_output": True }, "output": { "output_format": "json", "include_preview": True }}response = requests.post( f"{BASE_URL}/v1/synthesis/sync", headers={**auth_headers(), "Content-Type": "application/json"}, json=payload,)response.raise_for_status()data = response.json()print(data)const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = { Authorization: `Bearer ${TOKEN}`,};const payload = { "name": "quickstart-qa-preview", "synthesis_type": "qa_pairs", "engine_id": "deepeval", "source": { "type": "documents", "documents": [ "Cortex Parse turns URLs and storage objects into LLM-ready Markdown." ] }, "config": { "sample_count": 2, "max_contexts_per_case": 1, "include_expected_output": true }, "output": { "output_format": "json", "include_preview": true }};const response = await fetch(`${BASE_URL}/v1/synthesis/sync`, { method: "POST", headers: { ...authHeaders, "Content-Type": "application/json" }, body: JSON.stringify(payload),});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample { static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080"); static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token"); static final HttpClient HTTP = HttpClient.newHttpClient(); static void print(HttpResponse<String> response) { System.out.println(response.statusCode()); System.out.println(response.body()); } public static void main(String[] args) throws Exception { String json = """ { \"name\": \"quickstart-qa-preview\", \"synthesis_type\": \"qa_pairs\", \"engine_id\": \"deepeval\", \"source\": { \"type\": \"documents\", \"documents\": [ \"Cortex Parse turns URLs and storage objects into LLM-ready Markdown.\" ] }, \"config\": { \"sample_count\": 2, \"max_contexts_per_case\": 1, \"include_expected_output\": true }, \"output\": { \"output_format\": \"json\", \"include_preview\": true } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(BASE_URL + "/v1/synthesis/sync")) .header("Authorization", "Bearer " + TOKEN) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); print(HTTP.send(request, HttpResponse.BodyHandlers.ofString())); }}异步生成 job
import osimport requestsBASE_URL = os.getenv("CORTEX_URL", "http://127.0.0.1:8080")TOKEN = os.getenv("CORTEX_TOKEN", "replace_with_token")def auth_headers(): return {"Authorization": f"Bearer {TOKEN}"}payload = { "name": "quickstart-qa-preview", "synthesis_type": "qa_pairs", "engine_id": "deepeval", "source": { "type": "documents", "documents": [ "Cortex Parse turns URLs and storage objects into LLM-ready Markdown." ] }, "config": { "sample_count": 2, "max_contexts_per_case": 1, "include_expected_output": True }, "output": { "output_format": "json", "include_preview": True }}response = requests.post( f"{BASE_URL}/v1/synthesis/jobs", headers={**auth_headers(), "Content-Type": "application/json"}, json=payload,)response.raise_for_status()data = response.json()print(data)const BASE_URL = process.env.CORTEX_URL ?? "http://127.0.0.1:8080";const TOKEN = process.env.CORTEX_TOKEN ?? "replace_with_token";const authHeaders = { Authorization: `Bearer ${TOKEN}`,};const payload = { "name": "quickstart-qa-preview", "synthesis_type": "qa_pairs", "engine_id": "deepeval", "source": { "type": "documents", "documents": [ "Cortex Parse turns URLs and storage objects into LLM-ready Markdown." ] }, "config": { "sample_count": 2, "max_contexts_per_case": 1, "include_expected_output": true }, "output": { "output_format": "json", "include_preview": true }};const response = await fetch(`${BASE_URL}/v1/synthesis/jobs`, { method: "POST", headers: { ...authHeaders, "Content-Type": "application/json" }, body: JSON.stringify(payload),});if (!response.ok) throw new Error(await response.text());const data = await response.json();console.log(data);import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;public class CortexExample { static final String BASE_URL = System.getenv().getOrDefault("CORTEX_URL", "http://127.0.0.1:8080"); static final String TOKEN = System.getenv().getOrDefault("CORTEX_TOKEN", "replace_with_token"); static final HttpClient HTTP = HttpClient.newHttpClient(); static void print(HttpResponse<String> response) { System.out.println(response.statusCode()); System.out.println(response.body()); } public static void main(String[] args) throws Exception { String json = """ { \"name\": \"quickstart-qa-preview\", \"synthesis_type\": \"qa_pairs\", \"engine_id\": \"deepeval\", \"source\": { \"type\": \"documents\", \"documents\": [ \"Cortex Parse turns URLs and storage objects into LLM-ready Markdown.\" ] }, \"config\": { \"sample_count\": 2, \"max_contexts_per_case\": 1, \"include_expected_output\": true }, \"output\": { \"output_format\": \"json\", \"include_preview\": true } } """; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(BASE_URL + "/v1/synthesis/jobs")) .header("Authorization", "Bearer " + TOKEN) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); print(HTTP.send(request, HttpResponse.BodyHandlers.ofString())); }}