Python 调用 llama.cpp 运行的模型

参考前文，安装了 llama.cpp，并且部署好了一个本地翻译模型。

llama.cpp 在 Windows 11 上安装，并下载运行第一个本地模型

接下来，就是如何使用程序通过接口调用大模型了。例如：

llama-server -m Hy-MT2-1.8B-Q6_K.gguf --port 8080

运行起来之后，如何用 Python 调用模型，执行翻译任务。

Hello World

"""
Hy-MT2 翻译客户端 —— 调用本地 llama-server
前置条件：llama-server -m Hy-MT2-1.8B-Q6_K.gguf --port 8080
"""
from openai import OpenAI

client = OpenAI(
    api_key="not-needed",
    base_url="http://127.0.0.1:8080/v1"
)

def translate(text, target_lang="English", source_lang="Chinese"):
    prompt = (
        f"Translate the following text from {source_lang} to {target_lang}. "
        f"Note that you should only output the translated result "
        f"without any additional explanation:\n\n{text}"
    )

    response = client.chat.completions.create(
        model="Hy-MT2-1.8B-Q6_K",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.1,
        max_tokens=1024,
        stream=False
    )
    return response.choices[0].message.content.strip()

# 测试
if __name__ == "__main__":
    samples = [
        ("今天天气真好，我们去散步吧。", "English"),
        ("I love programming.", "Chinese"),
        ("La vie est belle.", "English"),
    ]
    for text, target in samples:
        print(f"[{target}] {translate(text, target_lang=target)}")

执行结果：

> python .\translate.py
[English] The weather is really nice today. Let’s go for a walk.
[Chinese] 我喜欢编程。
[English] Life is beautiful.

下面说明一下这段 Python 代码的实现逻辑。

为何使用 openai 库

因为 llama-server 完全兼容 OpenAI 的 Chat Completions 接口，可以直接用官方 openai 库调用，这样做的好处是，以后切换到其他方案，就不需要修改调用逻辑了。

当然也可以使用 http 请求的方法：

import requests

def translate(text, target_lang="English", source_lang="Chinese"):
    prompt = (
        f"Translate the following text from {source_lang} to {target_lang}. "
        f"Output only the translated text, no explanations.\n\n{text}"
    )

    response = requests.post(
        "http://127.0.0.1:8080/v1/chat/completions",
        json={
            "model": "Hy-MT2-1.8B-Q6_K",   # 与启动时的 --alias 一致（如有设置）
            "messages": [
                {"role": "user", "content": prompt}
            ],
            "temperature": 0.1,
            "max_tokens": 512
        },
        timeout=120
    )
    response.raise_for_status()
    return response.json()["choices"][0]["message"]["content"]

# 使用示例
result = translate("今天天气真好，我们去散步吧。", target_lang="English")
print(result)

Hy-MT2 专用提示词模板

Hy-MT2 是腾讯推出的翻译专用模型，官方推荐使用明确的指令格式。所以，才加入了这部分逻辑：

def build_hymt2_prompt(text, target_lang, source_lang="Chinese"):
    """Hy-MT2 官方推荐的翻译提示词"""
    return (
        f"Translate the following text from {source_lang} to {target_lang}. "
        f"Note that you should only output the translated result "
        f"without any additional explanation:\n\n{text}"
    )

# 中文提示词版本（可选）
def build_hymt2_prompt_zh(text, target_lang="英语"):
    return (
        f"将以下文本翻译成{target_lang}，"
        f"注意只需要输出翻译后的结果，不要额外解释：\n\n{text}"
    )

也可以根据自己需要增加定制化的提示词。

这段代码翻译一篇 10000 字的文章，可行么

直接用之前那段代码一次性翻译 10000 字的文章，基本不可行。主要会卡在以下几个地方：

• 上下文长度不够：Hy-MT2-1.8B 的上下文窗口通常只有 8K token 左右（即使大一点也有限）。10000 个汉字大约对应 10000～15000+ token，输入本身就可能超过模型上限。如果 llama-server 启动时没指定 –ctx-size，默认可能只有 512/2048，更容易直接报错或截断。
  
• max_tokens=1024 太小：这是输出 token 上限。10000 字文章的译文长度通常也接近 10000 字，对应 token 数远超 1024。结果就是翻译到一半被硬截断，后面全丢了。
  
• 超时与内存压力：一次性请求长文本，推理时间会很长，timeout=120 可能不够；同时 KV cache 占用大，1.8B 模型虽然小，但长上下文仍可能爆内存或变得极慢。
  
• 翻译质量下降：长文本一次性输入，模型容易“遗忘”前文、重复、漏译，尤其是 1.8B 这种小模型。