> ## Documentation Index > Fetch the complete documentation index at: https://docs.mka1.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar uma versão da suíte de avaliação > Cria uma versão imutável da suíte. Use este endpoint para edições em uma suíte de avaliação existente. ## OpenAPI ````yaml https://apigw.mka1.com/speakeasy.json?language=pt-BR post /api/v1/llm/evals/suites/{suite_id}/versions openapi: 3.1.1 info: title: MKA1 API version: 1.1.0 description: >- A API MKA1 é uma API RESTful que fornece acesso à plataforma MKA1. Aprenda como começar a usar a API e o SDK TypeScript [aqui](https://mka1.apidocumentation.com/guides/getting-started). license: name: Proprietário servers: - url: https://apigw.mka1.com description: MKA1 API Gateway - url: / description: Relative server URL (configurable via SDK constructor) security: [] tags: - name: Resource Authorization description: >- Gerencie permissões para recursos LLM. Crie recursos, conceda/revoque permissões e exclua recursos. Apenas os proprietários dos recursos podem conceder, revogar ou excluir permissões. x-displayName: Autorização de Recurso - name: Embeddings description: >- Endpoints da API de incorporação de texto para gerar representações vetoriais de texto. Crie incorporações semânticas para busca, clustering e correspondência de similaridade usando vários modelos de incorporação. x-displayName: Incorporações - name: Feedback description: >- API de feedback do usuário para avaliar e comentar sobre as conclusões de chat. Coleta de classificações de positivo/negativo e feedback detalhado para melhorar as respostas do modelo e acompanhar a satisfação do usuário. x-displayName: Feedback - name: Images description: >- Pontos de extremidade da API de geração de imagens para criar imagens a partir de descrições de texto. Gere imagens com controle sobre tamanho, qualidade e estilo. x-displayName: Imagens - name: MCP Vault description: >- API do cofre MCP para armazenar configurações de servidor MCP de propriedade do usuário e credenciais criptografadas. Os agentes referenciam IDs de cofre para que os segredos sejam resolvidos apenas no momento da execução da ferramenta. x-displayName: Cofre MCP - name: Speech description: >- Pontos de extremidade da API de fala para processamento de áudio. Converta texto em fala com som natural (TTS) ou transcreva fala em texto (STT) em diferentes idiomas. x-displayName: Discurso - name: Usage description: >- API de rastreamento de uso e análise para monitoramento do consumo de tokens, contagem de solicitações e análise de custos. Veja estatísticas detalhadas por usuário, modelo e período de tempo. x-displayName: Uso - name: Extract description: >- API de extração de dados estruturados para extrair informações de arquivos. Defina esquemas JSON para extrair dados estruturados de imagens, PDFs e documentos. Suporta modelos de esquema reutilizáveis. x-displayName: Extração - name: Text Classification description: >- API de classificação de texto para categorizar textos em rótulos predefinidos. Use modelos de IA para classificar o conteúdo textual para análise de sentimento, categorização de tópicos e moderação de conteúdo. x-displayName: Classificação de Texto - name: Responses description: >- API de respostas com agentes para criar agentes de IA com uso autônomo de ferramentas. Crie assistentes conversacionais que podem usar pesquisa na web, operações de arquivos, geração de imagens, execução de código, simulação de uso de computador e integrações MCP. Suporta processamento em segundo plano, streaming e monitoramento de status em tempo real. x-displayName: Respostas - name: Files description: >- API de gerenciamento de arquivos para upload, armazenamento e gerenciamento de arquivos com expiração automática e integração com S3. Faça upload de arquivos que podem ser usados com Assistentes, Armazenamentos Vetoriais e outras funcionalidades. Os arquivos são armazenados no S3 com metadados rastreados no PostgreSQL. Suporta limpeza automática de arquivos expirados. x-displayName: Arquivos - name: Vector Stores description: >- API de armazenamento de vetores para armazenar e pesquisar documentos usando embeddings. Crie armazenamentos de vetores, faça upload de arquivos com divisão automática e geração de embeddings, e realize pesquisas semânticas. Os arquivos são processados de forma assíncrona usando fluxos de trabalho Temporais para durabilidade. Suporta limpeza automática de armazenamentos expirados e LanceDB para armazenamento eficiente de vetores. x-displayName: Armazenamentos de Vetores - name: Conversations description: >- API de gerenciamento de conversas para armazenar e recuperar o estado da conversa durante chamadas à API de Resposta. Crie conversas, adicione itens (mensagens do usuário, mensagens do assistente, mensagens do sistema) e mantenha o histórico da conversa. Suporta rastreamento de metadados e gerenciamento de estado de diálogo em múltiplas interações. x-displayName: Conversa - name: Guardrails description: >- API de diretrizes de segurança de IA para configurar moderação de conteúdo e políticas de segurança. Configure listas de palavras proibidas, detecção de injeção de prompts e prevenção de vazamento de prompts do sistema. As diretrizes aplicam-se a todas as solicitações de uma conta e podem ser testadas antes da implementação. x-displayName: Guarda-corpos - name: Models description: >- API de listagem de modelos para descobrir modelos disponíveis. Retorna IDs de modelos, propriedade e metadados de todos os modelos registrados no gateway. x-displayName: Modelos - name: Skills description: >- API de habilidades para gerenciar pacotes versionados de instruções e arquivos seguindo o padrão de Habilidades do Agente. Crie, versionar e baixe pacotes de habilidades reutilizáveis que incluam manifestos SKILL.md para ambientes de agentes. x-displayName: Habilidades - name: Chat Completions description: >- **Obsoleto: Use a API de Respostas (`/api/v1/llm/responses`) em vez disso.** Endpoints de conclusão de chat com suporte para streaming, chamadas de ferramentas e múltiplos provedores. x-deprecated: true x-displayName: Conclusões de Bate-Papo - name: Batches x-displayName: Lotes - name: Evals x-displayName: Avaliações - name: Fine-Tuning x-displayName: Ajuste Fino - name: Memory Stores x-displayName: Armazenamentos de Memória - name: Prompts x-displayName: Sugestões - name: Tables description: Gerenciar esquemas de tabelas, operações de dados, pesquisa e índices. x-displayName: Tabelas - name: Text Store description: >- Gerencie armazenamentos de texto com busca híbrida (vetorial + texto completo) e conjuntos de texto agrupados. x-displayName: Loja de Texto - name: GraphRAG description: >- Construa e consulte gráficos de conhecimento leves respaldados por Redis e LanceDB. x-displayName: GraphRAG - name: API Key x-displayName: Chave da API - name: Sessions description: Crie, inspecione, acesse e encerre sessões de sandbox. x-displayName: Sessões - name: Browser description: >- Conecte-se às sessões do navegador através do proxy da porta do gateway. As sessões do navegador expõem um endpoint do Chrome DevTools Protocol na porta 9222. x-displayName: Navegador - name: Execution description: >- Executar comandos shell e código dentro de uma sessão de sandbox existente. x-displayName: Execução - name: Workspace description: >- Inspecione o manifesto do espaço de trabalho, transfira arquivos ou arquivos compactados e baixe artefatos gerados. x-displayName: Espaço de trabalho - name: Sandbox Usage x-displayName: Uso do Sandbox - name: Agents description: Crie e gerencie definições de agentes reutilizáveis. x-displayName: Agentes - name: Agent Versions description: >- Inspecione o histórico de configuração de um agente e reverta para uma versão anterior. x-displayName: Versões do Agente - name: Agent Runs description: Execute agentes salvos e inspecione os resultados da execução persistidos. x-displayName: Executa Agente - name: Agent Schedules description: Crie e gerencie execuções de agentes salvos agendadas ou recorrentes. x-displayName: Agendas de Agentes - name: schema-5_other x-displayName: outro paths: /api/v1/llm/evals/suites/{suite_id}/versions: post: tags: - Evals summary: Criar uma versão da suíte de avaliação description: >- Cria uma versão imutável da suíte. Use este endpoint para edições em uma suíte de avaliação existente. operationId: createEvalSuiteVersion parameters: - name: suite_id in: path required: true schema: type: string example: eval_suite_aa87e2b1112a455b8deabed784372198 - name: X-On-Behalf-Of in: header required: false schema: type: string description: Optional external end-user identifier forwarded by the API gateway. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEvalSuiteVersionRequest' example: manifest: schema_version: '2026-05-27' tasks: - id: spanish_qa type: custom dataset: source: huggingface path: IIC/AQuAS split: test num_fewshot: 1 prompt_template: |- Responde usando el contexto. Contexto: {{context}} Pregunta: {{question}} Respuesta: target_template: '{{answer}}' preprocess: type: python source: | def transform(row): return row grader: type: python contract: model_backed model_access: mka1 file_id: file_grader123 timeout_seconds: 120 make_active: true responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string object: const: eval.suite.version suite_id: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 manifest: type: object properties: schema_version: type: string default: '2026-05-27' tasks: type: array minItems: 1 maxItems: 100 items: anyOf: - description: One declarative eval task. - type: 'null' metadata: type: object propertyNames: type: string additionalProperties: {} default: {} required: - tasks dataset_file_ids: type: array items: type: string metadata: type: object propertyNames: type: string maxLength: 64 additionalProperties: type: string maxLength: 512 created_at: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - object - suite_id - version - manifest - dataset_file_ids - metadata - created_at security: - bearerAuth: [] x-codeSamples: - lang: python label: Python (SDK) source: |- from meetkai_mka1 import SDK with SDK( bearer_auth="", ) as sdk: res = sdk.llm.evals.create_suite_version(suite_id="eval_suite_aa87e2b1112a455b8deabed784372198", manifest={ "tasks": [ { "id": "spanish_qa", "type": "custom", "dataset": { "source": "huggingface", "path": "IIC/AQuAS", "split": "test", }, "prompt_template": "Responde usando el contexto.\n\nContexto: {{context}}\n\nPregunta: {{question}}\n\nRespuesta:", "target_template": "{{answer}}", "grader": { "type": "python", "contract": "model_backed", "model_access": "mka1", "file_id": "file_grader123", }, "preprocess": { "type": "python", "source": "def transform(row):\n return row\n", }, "num_fewshot": 1, }, ], }, make_active=True) # Handle response print(res) - lang: typescript label: Typescript (SDK) source: |- import { SDK } from "@meetkai/mka1"; const sdk = new SDK({ bearerAuth: "", }); async function run() { const result = await sdk.llm.evals.createSuiteVersion({ suiteId: "eval_suite_aa87e2b1112a455b8deabed784372198", createEvalSuiteVersionRequest: { manifest: { tasks: [ { id: "spanish_qa", type: "custom", dataset: { source: "huggingface", path: "IIC/AQuAS", split: "test", }, promptTemplate: "Responde usando el contexto.\n\nContexto: {{context}}\n\nPregunta: {{question}}\n\nRespuesta:", targetTemplate: "{{answer}}", grader: { type: "python", contract: "model_backed", modelAccess: "mka1", fileId: "file_grader123", }, preprocess: { type: "python", source: "def transform(row):\n return row\n", }, numFewshot: 1, }, ], }, }, }); console.log(result); } run(); - lang: csharp label: CSharp (SDK) source: |- using MeetKai.MKA1; using MeetKai.MKA1.Types.Components; using System.Collections.Generic; var sdk = new SDK(bearerAuth: ""); var res = await sdk.Llm.Evals.CreateSuiteVersionAsync( suiteId: "eval_suite_aa87e2b1112a455b8deabed784372198", body: new MeetKai.MKA1.Types.Components.CreateEvalSuiteVersionRequest() { Manifest = new EvalSuiteManifest() { Tasks = new List() { new EvalTask() { Id = "spanish_qa", Type = EvalTaskType.Custom, Dataset = new EvalDataset() { Source = SourceEnum.Huggingface, Path = "IIC/AQuAS", Split = "test", }, PromptTemplate = @"Responde usando el contexto. Contexto: {{context}} Pregunta: {{question}} Respuesta:", TargetTemplate = "{{answer}}", Grader = new EvalPythonGrader() { Contract = EvalPythonGraderContract.ModelBacked, ModelAccess = EvalPythonGraderModelAccess.Mka1, FileId = "file_grader123", }, Preprocess = new EvalPythonPreprocessor() { Source = @"def transform(row): return row ", }, NumFewshot = 1, }, }, }, } ); // handle response components: schemas: CreateEvalSuiteVersionRequest: type: object properties: manifest: $ref: '#/components/schemas/EvalSuiteManifest' metadata: type: object propertyNames: type: string maxLength: 64 additionalProperties: type: string maxLength: 512 default: {} make_active: type: boolean default: true required: - manifest EvalSuiteManifest: type: object properties: schema_version: type: string default: '2026-05-27' tasks: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/EvalTask' metadata: type: object propertyNames: type: string additionalProperties: {} default: {} required: - tasks EvalTask: type: object properties: id: type: string pattern: ^[A-Za-z0-9_.-]+$ name: type: string maxLength: 255 type: $ref: '#/components/schemas/EvalTaskType' dataset: $ref: '#/components/schemas/EvalDataset' prompt_template: type: string minLength: 1 target_template: type: string choices: type: array items: type: string output_extraction: $ref: '#/components/schemas/EvalOutputExtraction' default: type: none metrics: type: array items: $ref: '#/components/schemas/EvalMetric' grader: $ref: '#/components/schemas/EvalPythonGrader' preprocess: $ref: '#/components/schemas/EvalPythonPreprocessor' fewshot: $ref: '#/components/schemas/EvalFewshotConfig' num_fewshot: type: integer minimum: 0 maximum: 100 description: lm-eval estilo de alias para fewshot.count. metadata: type: object propertyNames: type: string additionalProperties: {} default: {} required: - id - type - dataset - prompt_template - grader description: Uma tarefa de avaliação declarativa. EvalTaskType: enum: - classification - multiple_choice - qa - summarization - semantic_similarity - llm_judge - numeric - math - custom EvalDataset: type: object properties: source: enum: - file - huggingface description: >- Fonte do conjunto de dados. Inferido a partir de file_id ou caminho quando omitido. file_id: type: string description: >- ID do arquivo para um conjunto de dados JSONL ou CSV carregado com a finalidade 'evals'. format: $ref: '#/components/schemas/EvalDatasetFormat' description: >- Formato do conjunto de dados. Inferido do nome do arquivo quando omitido. path: type: string description: Caminho do dataset do Hugging Face, por exemplo facebook/belebele. name: type: string description: Configuração do dataset Hugging Face/nome. split: type: string description: >- Hugging Face dividido para carregar, por exemplo, teste, treino ou validação. revision: type: string description: Revisão opcional do conjunto de dados Hugging Face. data_files: anyOf: - type: string - type: array items: type: string - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: array items: type: string description: >- Valor opcional de data_files do Hugging Face para conjuntos de dados no estilo json/csv/parquet. dataset_kwargs: type: object propertyNames: type: string additionalProperties: {} description: >- Argumentos adicionais de carregamento de conjuntos de dados retidos para metadados de importação/paridade. max_rows: type: integer minimum: 1 maximum: 1000000 description: >- Tampa de segurança opcional para carregamento remoto de conjuntos de dados. description: Conjunto de dados que apóia uma tarefa de avaliação. EvalOutputExtraction: anyOf: - type: object properties: type: const: none required: - type - type: object properties: type: const: take_first lines: type: integer minimum: 1 maximum: 10 default: 1 required: - type - type: object properties: type: const: regex pattern: type: string group: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: string default: 1 flags: type: string required: - type - pattern - type: object properties: type: const: regex_last pattern: type: string group: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: string default: 1 flags: type: string required: - type - pattern - type: object properties: type: const: label_set labels: type: array minItems: 1 items: type: string case_sensitive: type: boolean default: false required: - type - labels - type: object properties: type: const: number required: - type discriminator: propertyName: type mapping: {} EvalMetric: {} EvalPythonGrader: type: object properties: type: const: python contract: $ref: '#/components/schemas/EvalPythonGraderContract' default: sample description: >- Contrato Python para executar: nota de amostra(nota, item), lote nota_batch(amostras), ou model_backed com ajudantes de modelo ctx. execution: $ref: '#/components/schemas/EvalPythonGraderExecution' description: >- Se o avaliador roda por amostra ou uma vez no tempo de agregado/finalização. Padrões do contrato. model_access: $ref: '#/components/schemas/EvalPythonGraderModelAccess' description: >- Se o contexto do Python pode solicitar respostas MKA1 ou embeddings através da ponte de propriedade do gateway. metric_id: type: string pattern: ^[A-Za-z0-9_.-]+$ default: score description: Chave métrica padrão utilizada quando a nota retorna um único float. source: type: string minLength: 1 description: >- Código Python embutido que define um contrato de avaliação suportado. file_id: type: string description: >- ID do arquivo para um avaliador Python enviado com o propósito 'evals'. timeout_seconds: type: integer minimum: 1 maximum: 600 default: 120 max_model_calls: type: integer minimum: 0 maximum: 500 default: 64 required: - type EvalPythonPreprocessor: type: object properties: type: const: python contract: enum: - row - batch default: row description: >- Execute transform(row) para cada linha ou transform_batch(rows) uma vez. source: type: string minLength: 1 description: >- Fonte Python em linha que transforma as linhas do conjunto de dados antes da renderização do prompt. file_id: type: string description: >- ID do arquivo para um pré-processador Python enviado com o propósito 'evals'. timeout_seconds: type: integer minimum: 1 maximum: 600 default: 120 required: - type EvalFewshotConfig: type: object properties: count: type: integer minimum: 0 maximum: 100 default: 0 dataset: description: Conjunto de dados separado opcional usado para exemplos de few-shot. prompt_template: type: string description: >- Modelo de prompt opcional para exemplos de few-shot. Padrão para prompt_template da tarefa. target_template: type: string description: >- Modelo de alvo opcional para exemplos de poucos disparos. O padrão é o modelo de alvo da tarefa. example_template: type: string default: |- {{prompt}} {{target}} description: Modelo para um exemplo de few-shot renderizado. separator: type: string default: |+ description: Separador entre exemplos de few-shot e o prompt avaliado. strategy: enum: - first - random default: first seed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 default: 0 EvalDatasetFormat: enum: - jsonl - csv EvalPythonGraderContract: enum: - sample - batch - model_backed EvalPythonGraderExecution: enum: - per_sample - aggregate EvalPythonGraderModelAccess: enum: - none - mka1 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Gateway auth: send `Authorization: Bearer `. For multi-user server-side integrations, you can also send `X-On-Behalf-Of: `. ````