#Usar Lina e HY-MT1.5-1.8B local para traduzir entradas de localização

Este guia descreve uma prática de tradução de localização: implantar localmente um pequeno modelo especializado em tradução, expô-lo como serviço compatível com OpenAI e configurá-lo para que Lina traduza em lote as entradas de localização do NocoBase.

Esta abordagem é adequada para muitas entradas do sistema, textos de plugins, menus, títulos de coleções e rótulos de campos. Em comparação com modelos online, modelos locais não são afetados por limites externos de RPM, TPM ou concorrência, e a concorrência pode ser ajustada conforme a capacidade da máquina e do modelo.

#Visão geral

Este guia usa:

• Modelo: tencent/HY-MT1.5-1.8B-GGUF
• Serviço de inferência: llama-server
• Integração: OpenAI-compatible API
• Funcionária de IA: Lina
• Ponto de entrada: página Localization Management

#Pré-requisitos

• O plugin Localization Management está ativado.
• O idioma de destino está ativado.
• As entradas de localização foram sincronizadas.
• A máquina local ou servidor pode executar llama-server.
• O serviço NocoBase consegue acessar o endereço HTTP do llama-server.

#Implantar HY-MT GGUF

#Instalar llama.cpp

No macOS, você pode instalar com Homebrew:

brew install llama.cpp

Também é possível usar um binário pré-compilado do llama.cpp ou compilá-lo a partir do código-fonte. O requisito final é que llama-server esteja disponível.

#Iniciar um serviço compatível com OpenAI

Inicie o serviço com o modelo GGUF do Hugging Face:

llama-server \
  -hf tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M \
  --host 0.0.0.0 \
  --port 8000 \
  -c 2048 \
  -np 4

#Testar o serviço do modelo

Depois que llama-server iniciar, verifique a saúde do serviço:

curl http://127.0.0.1:8000/health

Em seguida, teste a tradução pela API compatível com OpenAI:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M",
    "messages": [
      {
        "role": "user",
        "content": "Translate the following text into Chinese. Output only the translated result without any additional explanation:\n\nSave"
      }
    ]
  }'

Se você iniciar a partir de um arquivo de modelo local, altere model para o nome real retornado ou configurado pelo serviço.

#Configurar um serviço LLM no NocoBase

Acesse System Settings -> AI Employees -> LLM service e adicione um serviço LLM.

Após configurar, use Test flight para verificar o modelo.

#Configurar o modelo dedicado da Lina

Acesse System Settings -> AI Employees -> AI employees, abra Lina e mude para Model settings.

1. Ative Enable dedicated model configuration.
2. Selecione o modelo HY-MT local em Models.
3. Salve a configuração.

Depois disso, Lina usará esse modelo para tarefas de tradução de localização e evitará alternar para modelos gerais de chat.

Para detalhes, consulte Configurar modelos de funcionários de IA.

#Configurar a concorrência de tradução

A concorrência das tarefas de tradução de localização é controlada por AI_LOCALIZATION_CONCURRENCY:

AI_LOCALIZATION_CONCURRENCY=10

Regras:

• Padrão: 10
• Mínimo: 1
• Máximo: 20
• Valores fora do intervalo usam o padrão

A melhor concorrência depende de CPU, GPU, memória, quantização do modelo e llama-server -np. Se a concorrência padrão causar problemas:

1. Comece com AI_LOCALIZATION_CONCURRENCY=1 e verifique a tradução de uma única entrada.
2. Defina llama-server -np e AI_LOCALIZATION_CONCURRENCY como 2 ou 4.
3. Observe tempo de resposta, uso de CPU/GPU e progresso da tarefa.
4. Aumente gradualmente somente se estiver estável.

#Executar a tradução de localização

Acesse System Management -> Localization Management.

1. Mude para o idioma de destino.
2. Clique em Synchronize para garantir que as entradas estejam sincronizadas.
3. Clique no avatar da Lina.
4. Escolha um escopo de tarefa:
   • Incremental translation: traduz entradas sem tradução.
   • Selected translation: traduz entradas selecionadas na tabela.
   • Full translation: traduz todas as entradas no idioma atual.
5. Verifique a quantidade de entradas, o provedor e o modelo na caixa de confirmação.
6. Confirme para criar a tarefa assíncrona.
7. Aguarde a conclusão, revise as traduções e publique.

Comece com Selected translation em algumas entradas para verificar o estilo e a velocidade antes de executar tradução incremental ou completa.

#Como Lina constrói as solicitações de tradução

Lina constrói solicitações a partir das entradas e traduções de referência. Para entradas curtas, referências existentes ajudam a melhorar a consistência:

• Entradas integradas preferem traduções em chinês como referência.
• Entradas não integradas preferem o idioma padrão do sistema como referência.
• Se houver uma referência em inglês, o inglês é usado como texto de origem.
• Os resultados são gravados no idioma de destino, mas não são publicados automaticamente.

A semântica do prompt é semelhante a:

Refer to the following translation:
{source_term} is translated as {target_term}

Translate the following text into {target_language}. Output only the translated result without any additional explanation:

{source_text}

#Solução de problemas

#Sem progresso após criar uma tarefa

Verifique se llama-server recebeu solicitações. Veja os logs do serviço ou chame /v1/chat/completions com curl.

Se o modelo recebe solicitações mas não retorna, reduza:

• AI_LOCALIZATION_CONCURRENCY
• llama-server -np
• llama-server -c

#O modelo retorna explicações em vez de traduções

Modelos locais de tradução costumam ser mais estáveis do que modelos gerais de chat. Se ainda aparecerem explicações, teste primeiro o mesmo prompt com curl para verificar o estilo de saída do modelo. Você também pode traduzir entradas mais curtas primeiro ou reduzir parâmetros de amostragem como temperature.

#NocoBase não consegue conectar ao serviço do modelo

Verifique:

• Se Base URL inclui /v1.
• Se o ambiente de execução do NocoBase consegue acessar o endereço.
• Se firewall ou rede de contêiner bloqueia a porta.
• Se llama-server ainda está em execução.

#Revisar antes de publicar

Depois que a tradução por IA terminar, revise antes de publicar:

• Filtre por módulo e verifique entradas curtas como menus, botões, nomes de campos e status.
• Verifique variáveis, placeholders, tags HTML e símbolos de formatação.
• Verifique a consistência dos principais termos de negócio.
• Se traduções de entradas integradas forem sobrescritas, sincronize novamente em Localization Management e selecione Reset system built-in entry translations para restaurar os padrões. Para contribuir traduções padrão do sistema e plugins oficiais, consulte Translation Contribution.
• Publique primeiro em um ambiente de teste e depois sincronize para produção.

#Referências

• tencent/HY-MT1.5-1.8B-GGUF
• Documentação do llama-server
• Lina: engenheira de localização